docs
OverviewCommerce APIStorefront APIUser GuideExplorer
JSON API > Introduction
Search docs
/
Sign In
OverviewJSON APIIntroduction
Introduction

The primary method of communication with the Lana backend is the GraphQL API. However, there is also an available raw HTTP JSON API endpoint that exposes the same set of features. Depending on the situation, you might find it more suitable to use this API. The JSON API allows access to both the commerce and storefront API functionalities.

The key difference between the two APIs lies in type safety. Both APIs are supported by libraries and code generators that facilitate type-safe operations. The JSON API provides a predefined set of types, while GraphQL allows you to define these types (such as fragments) when constructing queries and mutations in a .graphql file. For instance, when you fetch a list of products, you may not require a detailed description for each product. In such a case, you can simply omit these fields in GraphQL, which will then be reflected in the generated types. JSON client library wrappers do not possess such functionality, even though the JSON API allows you to omit certain fields using the fields parameter. Therefore, type safety is an important consideration in choosing between the two.

The JSON API endpoint is https://api.lana.dev/relay.json.

The JSON API allows batch requests. This means you can resolve multiple individual Lana API requests within a single HTTP request, similar to resolving multiple top level fields in GraphQL query/mutation.

Request

Each request must use a POST method and contain a JSON body of the following structure (Request in typescript pseudo-code below):

// An array of individual requests
export type Request = SingleRequest[];

interface SingleRequest {
  "method"?: "POST" | "GET" | "DELETE"; // Method of the batched request, `POST` by default.
  "url": string; // Part of the URL, excludes host part. This is a required field.
  "request"?: any; // JSON body of the request
  "expansions"?: []string; // List of fields to be expanded in the output
}
  • method - Method of the batched request, POST by default.
  • url - This consists of the path and arguments of the request. Note that this is only part of the URL; the host part should be excluded. This is a required field. A valid URL might look like: products/page.json?shop_id=sh_4jh34kj54y&offset=0&limit=5.
  • request - The JSON body of the request, if the individual request implies the use of a request body.
  • expansions - A list of fields to be expanded in the output, such as ["items.variants"] (for GET:products/page.json)

The HTTP request also acknowledges the following headers:

You can consult the GraphQL documentation on this portal to find valid method/URL combinations. Each GraphQL mutation/query page includes the method/URL path section below the page header.

Response

The top-level HTTP status code will apply the standard HTTP status codes as needed:

  • 200 <= x < 300 - Successful response.
  • 400 - Bad Request: Returned if the request is malformed or any individual requests fail.
  • 401 - Unauthorized: Returned if JWT validation fails.
  • 404 - Not Found: Returned if an item or API endpoint isn't found.
  • 429 - Too Many Requests: Try again later due to rate limiting.
  • ... - Etc. Any defined HTTP status codes may be returned.

The response will be structured as follows (Response in TypeScript pseudo-code):

// An array of individual responses
export type Response = SingleResponse[];

interface SingleResponse {
  status: number; // HTTP status code of an individual response
  response?: any; // JSON data if the response was successful
  error?: any; // Details about the error if the response was unsuccessful
}

Once you receive a valid response, disregard the top-level HTTP status code and focus on the individual response codes. The status field contains the HTTP status code of an individual response. If the response is successful, it will include a response field with relevant JSON data. If not, it will include an error field with more detailed error information.

NOTE

Unsuccessful field expansion is not considered an error and will not be reported as such.

Language-specific Wrappers

If available for your programming language, consider using type-safe API wrappers:

PREVIOUS
JSON API
NEXT
Tutorial