topics

Content

Introduction

Lingo JS makes it easy to get up and running with the Lingo API in a node context with just a few lines of code. The package is typed with typescript making it even easier to learn the available APIs in an IDE.

We recommend using modern javascript module syntax. To simplify setup you can also checkout our template start project @lingo-app/JSDemo.

If you are unfamiliar with the types of objects and data model you may want to review the Glossary.

If you have anny questions or would like to see additional functionality added, please open an issue or submit a PR in the GitHub repo.

Installing

npm install @lingo-app/node --save-dev
// or
yarn add -D @lingo-app/node
import Lingo from "@lingo-app/node"

Install @lingo-app/node with npm or yarn then import it into a javascript or typescript file.

Authentication

const spaceID = 123;
const apiToken = "wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJE";
lingo.setup(123, apiToken);

Before making any API calls call setup with your space and api token to use for authentication

Error Codes

lingo.fetchKit('deleted-kit-uuid').catch(err => {
  if (err.code == lingo.Error.Code.kitNotFound) {
    console.log("Oops, this kit isn't available")
  }
})

// The available error codes
{
  unknown: 1,
  serverError: 99,
  invalidParams: 103,
  unauthorized: 401,
  permissionDenied: 403,
  objectNotFound: 404,
  rateLimited: 429,

  kitNotFound: 1100,
  versionNotFound: 1200,
  sectionNotFound: 2100,
  assetNotFound: 3100,
  fileCutUnavailable: 3304,
};

Every lingo error will include one of the codes listed here. Note that most fetches will return a specific error for the type of object being fetched.

Kits

Get all Kits

lingo.fetchKits().then(kits => {

  })
  .catch(err => {

  });

Returns a list of all kits in the space

Kit Versions

lingo.fetchKit('3BD9CDAF-14DF-495A-AA2F-4993092D62EE', 'versions').then(kits => {

}).catch(err => {

})

Returns a single kit and its versions

Parameters  
idstring - required The uuid of the kit to fetch
includestring Optionally include the versions of the kit. Valid options include versions, use_versions, empty.

Include options

Kit Outline


lingo.fetchKitOutline('3BD9CDAF-14DF-495A-AA2F-4993092D62EE', 0).then(sections => {

}).catch(err => {

})

Retrieve the outline of a kit consisting of a list of sections and the headers within each section.

Parameters  
idstring - required The uuid of the kit to fetch
versioninteger The version of the kit to fetch.

Sections

Fetch A Section

lingo
  .fetchSection("B1F7A3DD-4E6E-4799-8673-4F857ECC388E", 0)
  .then(section => {})
  .catch(err => {});

Retrieve a section and optionally the items with it, paging through items as needed.

Parameters  
idstring - required The id of the section.
versioninteger The version of the section/kit to fetch. (default 0)
pageinteger The page number to retrieve when paging through results (default 1).
limitinteger The max number of items to retrieve, up to 200 or 0 for no items (default 50).

Fetch All Section Items

lingo
  .fetchAllItemsInSection("B1F7A3DD-4E6E-4799-8673-4F857ECC388E", 0)
  .then(items => {})
  .catch(err => {});

A utility function to fetch all items in a section.

The API limits item fetches to 200. This function recursively calls fetchSection until all items have been retrieved then returns the full list of items.

To manually page through items, use fetchSection.

Parameters  
idstring - required The id of the section.
versioninteger The version of the section/kit to fetch. (default 0)

Heading Contents

lingo
  .fetchItemsForHeading("B1F7A3DD-4E6E-4799-8673-4F857ECC388E", "D86B229B-0171-4EA3-893D-456760D3E8EF")
  .then(items => {})
  .catch(err => {});

Retrieve the content within a section that fall under a particular heading.

Parameters  
sectionIdstring - required The id of the section.
headingIdstring - required The id or name of the section. Note that with name, the first match is used.
versioninteger The version of the section/kit to fetch.

Assets

Download

lingo.downloadAsset('9CD0AFF5-B050-4B97-8E65-185F969686D5', 'PNG').then(download => {

}).catch(err => {

})

Download the file for an asset or one of its available file cuts

Note: The download endpoint is currently rate limited to 2000 every 5 minutes.

Parameters  
assetIdinteger The id of the asset.
typestring The file format to download, or null for the original (default: null).

Available File Cuts

Original Cuts
SVG PNG, PDF, EPS
JPG PNG
PNG JPG
GIF JPG, PNG
EPS PNG
PDF PNG
TIFF PNG, JPG
Sketch SVG, PNG, PDF

Search

Lingo search provides a powerful way to find content.

LingoJS uses a object to make it easy to build and perform search queries. Before getting into the details it’s important to know that there are a few main types of content you can search for:

Kits, sections and headings are organization objects in Lingo which can be used to fetch groups of content. Searching for them through the API can be useful if you aren’t sure exactly which kit or section you need to fetch from.

Searching For Kits

const response = await lingo.search().kits().matchingKeyword("Brand").fetch()
const kits = response.results.map(res => res.object)

Returns a list of all kits matching “Brand”. Similiarly you can call .sections() or .headings() to search for those. By default a search will return content results so you don’t need to do anything there, though you can call .content() if you’d like.

Beacuse search can return different types of objects in the same array, each result is wrapped in an object with two kets: type and object. In the example above we can assume that all the obejcts will be kits since we specifcially restricted the query to .kits().

Filters


const result = await lingo.search()
  .inKit(kitId) // in a specific kit
  .matchingKeyword("Logo") // name, tag or description contains logo
  .withTag("branding") // has tag 'branding'
  .ofType("images") // an image type
  .after("2020-05-01") // created after may 1
  .before("2020-06-01"); // created before june 1
  .fetch()

console.log(`Found ${result.total} matches!`)
const items = result.results.map(res => res.object)

There are a few different filters you can use to narrow down your searches. This example makes use of all availble filters to find some logo/branding assets

Some filter functions can be called more than once. The resulting query in some cases will use an OR operator for those values. For example, .ofType("JPG").ofType("PNG") will look for JPG and PNG assets. Keyword and tag matches will produce an AND operator. The before and after filters should only be added once to any given searhc.