JSON:API Guide

Terminal49’s API follows the JSON:API specification, a standard for building APIs in JSON. This guide will help you understand the key concepts and how to work with our API effectively.

What is JSON:API?

JSON:API is a specification for how a client should request resources to be fetched or modified, and how a server should respond. It’s designed to minimize both the number of requests and the amount of data transmitted between clients and servers.

The Terminal49 API conforms to the JSON:API v1.0 specification. This standardization makes our API more predictable and easier to work with once you understand the patterns.

Why Terminal49 Uses JSON:API

Terminal49 uses the JSON:API specification for a number of important reasons that directly benefit developers working with shipping and container tracking data:

Standardized Relationships for Complex Shipping Data

Shipping data is inherently relational - containers belong to shipments, shipments have transport events, containers have tracking events, and all these relate to carriers, terminals, and vessels. JSON:API excels at representing these complex relationships through:

Consistent Structure: Every response follows the same pattern, making data predictable and easy to parse
Clear Resource Relationships: Explicit definition of how resources like shipments, containers, and events relate to each other
Compound Documents: The ability to include related resources in a single request, eliminating the need for multiple API calls

Efficient Data Loading for Shipping Operations

JSON:API’s approach to related data is particularly valuable for shipping operations:

{
  "data": {
    "id": "123",
    "type": "shipment",
    "attributes": {
      "bill_of_lading_number": "MAEU1234567",
      "carrier_name": "Maersk"
    },
    "relationships": {
      "containers": {
        "data": [
          { "id": "456", "type": "container" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "456",
      "type": "container",
      "attributes": {
        "number": "MRKU1234567",
        "size_type": "40HC"
      }
    }
  ]
}

This allows Terminal49 to deliver a complete picture of your shipping data in fewer requests, which means:

Reduced API Calls: Get containers and their shipments in a single request
Minimized Latency: Critical for time-sensitive logistics operations
Lower Bandwidth: Only request the related objects you need, when you need them

Standardized Error Handling

JSON:API provides a consistent format for error responses, making it easier to:

Identify Issues: Clearly pinpoint which field or relationship has an error
Implement Error Handling: Write consistent error handling logic across your application
Debug Problems: Receive detailed information about what went wrong and why

Client Libraries

Instead of writing custom code to parse JSON:API responses, you can leverage ready-made libraries for most programming languages:

JavaScript

JSON:API libraries for JavaScript

Ruby

jsonapi-rb for Ruby applications

Python

JSON:API libraries for Python

PHP

PHP client libraries for JSON:API

Go

Go implementations of JSON:API

Java

Java frameworks for JSON:API

These libraries provide significant benefits when working with Terminal49’s API:

Automatic Relationship Resolution: Easily navigate from shipments to containers and events without manual mapping
Type Conversion: Convert API responses into native language objects/models
Query Building: Construct complex API queries with simple, intuitive methods
Consistent Updates: Standardized methods for creating and updating resources
Error Handling: Built-in support for JSON:API error formats

Using these libraries can reduce development time by up to 50% when working with complex shipping data structures, allowing you to focus on your business logic rather than API parsing details.

JSON:API Structure

Basic Resource Objects

All Terminal49 API responses follow this general structure:

{
  "data": {
    "id": "123",
    "type": "shipment",
    "attributes": {
      "bill_of_lading_number": "MAEU9736478",
      "created_at": "2023-05-15T14:23:12Z"
      // Other shipment attributes
    },
    "relationships": {
      "containers": {
        "data": [
          { "id": "456", "type": "container" },
          { "id": "789", "type": "container" }
        ]
      }
    }
  }
}

The main components are:

data

object

The primary resource or collection of resources.

string

A unique identifier for the resource.

type

string

The resource type (e.g., “shipment”, “container”, “tracking_request”).

attributes

object

The resource’s properties (e.g., numbers, dates, status values).

relationships

object

References to related resources (e.g., a shipment’s containers).

Collections of Resources

When requesting multiple resources, the response structure is:

{
  "data": [
    {
      "id": "123",
      "type": "shipment",
      "attributes": { ... }
    },
    {
      "id": "124",
      "type": "shipment",
      "attributes": { ... }
    }
  ],
  "meta": {
    "total_count": 45
  },
  "links": {
    "self": "https://api.terminal49.com/v2/shipments?page[number]=1&page[size]=2",
    "next": "https://api.terminal49.com/v2/shipments?page[number]=2&page[size]=2"
  }
}

Working with JSON:API in Terminal49

Creating Resources

When creating a resource (like a tracking request), your request should follow this format:

{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MAEU9736478",
      "scac": "MAEU"
    }
  }
}

Notice that:

The type field is required and must match the expected resource type
All properties go inside the attributes object
You don’t specify an id for new resources (the server assigns it)

One powerful feature of JSON:API is the ability to include related resources in a single request using the include parameter:

GET /shipments/123?include=containers,containers.transport_events

This returns the shipment with its containers and each container’s transport events in one response:

{
  "data": {
    "id": "123",
    "type": "shipment",
    "attributes": { ... },
    "relationships": {
      "containers": {
        "data": [
          { "id": "456", "type": "container" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "456",
      "type": "container",
      "attributes": { ... },
      "relationships": {
        "transport_events": {
          "data": [
            { "id": "789", "type": "transport_event" }
          ]
        }
      }
    },
    {
      "id": "789",
      "type": "transport_event",
      "attributes": { ... }
    }
  ]
}

included

array

Contains all the related resources referenced in the main resource’s relationships.

Error Handling

Error responses also follow a standard format:

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid attribute",
      "detail": "The SCAC 'UNKNOWN' is not supported.",
      "source": {
        "pointer": "/data/attributes/scac"
      }
    }
  ]
}

Each error object contains:

status

string

The HTTP status code relevant to the error.

title

string

A short, human-readable summary of the problem.

detail

string

A human-readable explanation of the specific error.

source

object

An object containing references to the source of the error. The pointer field typically contains a JSON Pointer to the specific field that caused the error.

Tips for Working with Terminal49’s JSON:API

Always include the correct Content-Type header in your requests:
```
Content-Type: application/vnd.api+json
```
Use the include parameter to reduce the number of API calls when you need related resources
When creating or updating resources, remember that all properties must be inside the attributes object
For filtering collections, use the filter query parameter with the attribute name:
```
GET /containers?filter[status]=arrived
```
Pagination is handled via page[number] and page[size] query parameters

For a deeper understanding of JSON:API, check the official specification or our In-Depth Guides on working with Terminal49’s API.

​JSON:API Guide

​What is JSON:API?

​Why Terminal49 Uses JSON:API

​Standardized Relationships for Complex Shipping Data

​Efficient Data Loading for Shipping Operations

​Standardized Error Handling

​Client Libraries

JavaScript

Ruby

Python

PHP

Go

Java

​JSON:API Structure

​Basic Resource Objects

​Collections of Resources

​Working with JSON:API in Terminal49

​Creating Resources

​Including Related Resources

​Error Handling

​Tips for Working with Terminal49’s JSON:API

JSON:API Guide

What is JSON:API?

Why Terminal49 Uses JSON:API

Standardized Relationships for Complex Shipping Data

Efficient Data Loading for Shipping Operations

Standardized Error Handling

Client Libraries

JSON:API Structure

Basic Resource Objects

Collections of Resources

Working with JSON:API in Terminal49

Creating Resources

Including Related Resources

Error Handling

Tips for Working with Terminal49’s JSON:API