Developer Notes

Various notes on Developer Experience (DX) and performance of Spire API

Use GZIP Compression#

Spire production GraphQL API api.spire.com/graphql supports GZIP compression of the output. Since JSON payload is mostly text, it compresses exceptionally well with GZIP. You can gain up to 20% reduction in payload size using GZIP compression in production.

We encourage our clients to send the header alongside with requests:

Accept-Encoding: gzip, deflate

For example:

curl --request POST \                                                                                                     ~/Dev/maritime-customer-documentation
  --url https://api.spire.com/graphql \
  --header 'Accept-Encoding: gzip,deflate' \
  --header 'Authorization: Bearer <insert-token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query{ vessels(first: 99) { nodes{ staticData { name mmsi imo } } } }"}'

Query What you Need#

Unlike REST where the endpoint defines the resource and the received data, the GraphQL exposes a single endpoint with a global schema where you can query whatever you want. The ability to define precisely the data you want — and only the data you want — is a powerful advantage over traditional REST API endpoints.

By making focused queries you can focus on data you need and omit unimportant one. If you need just vessel positions, then query for vessel positions and omit everything else. If you need vessel characteristics, then query for vessel positions and omit everything else.

The following example shows the query focused only on getting only positional information about the vessels:

query queryVesselsPositions(
  $limit: Int
  $after: String
  $startTime: DateTime!
  $endTime: DateTime!
) {
  vessels(
    first: $limit
    after: $after
    lastPositionUpdate: { startTime: $startTime, endTime: $endTime }
  ) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      id
      staticData {
        mmsi
      }
      lastPositionUpdate {
        timestamp
        latitude
        longitude
        heading
        speed
        rot
        accuracy
        course
        maneuver
        navigationalStatus
      }
    }
  }
}

Querying only what you need together with GZIP compression could significantly reduce the amount of transferred data and therefore increase the performance.

Schema as live Documentation#

The api.spire.com/graphql provides a GraphQL playground where you could create and execute a query of any complexity. This is perfect environment where you can prepare you query for production usage. The Docs button in the right top corner provides detailed information about GraphQL schema including query structure, fields and comments.

GraphQL Playground

Request Ids#

Each response from GraphQL payload contains an extensions object which has a requestId field:

{
  "data": { ... },
  "extensions": {
    "requestId": "7246b710-145d-4528-9c74-972287dc713a"
    ...
  }
}

In case of any troubles or unclear errors, provide the requestId to our support team. We use the requestId to track down the cause of the issue you're dealing with in a faster and more efficient manner.