The Lana platform primarily uses the GraphQL API for communication with the backend. However, a raw HTTP JSON API is also available, exposing the same features for both the Commerce API and Storefront API. Depending on your use case, the JSON API might be more suitable.

JSON API vs. GraphQL API

The key difference between the JSON and GraphQL APIs is type safety:

• GraphQL API: Allows you to define custom types (fragments) in .graphql files when constructing queries and mutations. For example, when fetching a product list, you can omit fields like detailed descriptions, and the generated types reflect only the requested fields.

• JSON API: Provides a predefined set of types. You can omit fields using the fields query parameter, but JSON client libraries do not offer the same level of type safety as GraphQL.

Choose the JSON API when you need a simpler, HTTP-based interface or when type safety is less critical.

JSON API Endpoints

Access the JSON API via endpoints at https://api.lana.dev/*, where * represents a specific path and arguments. For example: https://api.lana.dev/products/page.json?shop_id=sh_ABd45EZBeE81. To find valid method and URL combinations, refer to the GraphQL documentation on this portal. Each query or mutation page includes a method/URL path section below the page header.

Batch Requests

The JSON API supports batch requests through the https://api.lana.dev/relay.json endpoint. This allows you to combine multiple API requests into a single HTTP request, similar to resolving multiple top-level fields in a GraphQL query or mutation.

Batch Request Format

Send batch requests to https://api.lana.dev/relay.json using the HTTP POST method. The request body must be a JSON array of individual requests, structured as follows:

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

interface SingleRequest {
  "method"?: "POST" | "GET" | "DELETE"; // HTTP method for the request. Defaults to "POST".
  "url": string; // Path and arguments of the request, excluding the host. Required.
  "request"?: any; // JSON body for the request, if applicable.
  "expansions"?: []string; // List of fields to expand in the response, e.g., ["items.variants"].
}

• method - The HTTP method for the individual request. Defaults to POST.
• url - The path and query parameters, excluding the host (e.g., products/page.json?shop_id=sh_4jh34kj54y&offset=0&limit=5). Required.
• request - The JSON body for the individual request, if required by the endpoint.
• expansions - A list of fields to expand in the response, specified as dot-separated paths (e.g., ["items.variants"]).

Batch Response Format

The response is a JSON array of individual responses, structured as follows:

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

interface SingleResponse {
  status: number; // HTTP status code for the individual response.
  response?: any; // JSON data for a successful response.
  error?: any; // Error details for an unsuccessful response.
}

• status: The HTTP status code for the individual response (e.g., 200 for success, 400 for bad request).
• response: Contains the JSON data if the request was successful.
• error: Contains error details if the request failed.

The top-level HTTP status code reflects standard HTTP conventions:

• 200–299: Success.
• 400: Bad request (malformed request or individual request failure).
• 401: Unauthorized (JWT validation failure).
• 404: Not found (invalid endpoint or resource).
• 429: Too many requests (rate limit exceeded).

Always check the status field of each individual response, as the top-level HTTP status code may not fully reflect the outcome of all batched requests.

NOTE

Unsuccessful field expansions are not reported as errors.

Supported HTTP Headers

The JSON API supports the following HTTP headers:

• Authorization
• Idempotency-Key
• Locale
• Session-Id
• Device-Id

Language-specific Wrappers

For type-safe interactions, use the following language-specific wrapper:

• TypeScript/JavaScript: https://www.npmjs.com/package/@lana-commerce/core (json/commerce or json/storefront).

Field Expansions

To reduce roundtrip time, you can expand specific fields in the response using the expansions parameter. Specify fields as dot-separated paths (e.g., items.variants).

• Individual Endpoints: Use the expansions query parameter with a comma-separated list of fields (e.g., products/page.json?expansions=items.variants).
• Batch Requests:Include an expansions array in each SingleRequest (e.g., ["items.variants"]).

Fields Query Parameter

Use the fields query parameter to include or exclude specific fields in the response. Fields are specified as a comma-separated list. To exclude a field, prefix it with a minus sign (-).

• Individual Endpoints: Append to the URL (e.g., products/page.json?fields=id,title).

• Batch Requests: Append to the url field of each SingleRequest (e.g., products/page.json?fields=id,title).

For page.json endpoints, fields under items are treated as root fields, so you don't need to specify the full path. Nested fields are specified with a dot (e.g., variants.sku).

Field Selection Rules

• Include fields: When include is defined (e.g., id,title), only the specified fields are returned in the response.
• Exclude fields: When exclude is defined (e.g., -id,-title), all fields are returned except those explicitly excluded.
• Includes take precedence: If a field is listed in both includes (e.g., title) and excludes (e.g., -title), the include takes precedence.
• Nested fields: Specify nested fields with dots (e.g., variants.sku).
• Expansions required: To include fields of expandable objects, you must also specify the corresponding object in the expansions parameter.

Example 1.

products/page.json?fields=id,title,-title

Returns products with id and title fields. The include list (id, title) overrides the exclude list (-title).

Example 2.

products/page.json?fields=variants.sku&expansions=items.variants

Returns all product fields, with only the sku field for variants. The expansions parameter is required to include variants.

Example 3.

products/page.json?fields=variants,variants.sku&expansions=items.variants

Returns products with only the variants field, and within variants, only the sku field. The expansions parameter is required.