API Specifications

We provide technical specifications for all endpoints using the two most widely adopted REST-ful API definition systems.

This documentation forms part of the suite of technical resources which we provide in order to help developers make use of the Spike API.

OpenApi

OpenApi (opens new window) (formerly Swagger) defines all inputs and outputs from each function^[1] along with examples of these inputs and outputs. Each function definition is contained within a single .json (or .yaml) file. This json can be used for automatic client code generation but this is typically overkill, it's primarily useful as a reference document (e.g. to see all possible response shapes and to define any enumeration values).

Here are the links to the Spike OpenAPI definitions:

Collection	Function	OpenApi definition
Spike Statements API	/pdf1	spike-api-statements-pdf1.openapi.json
Spike Statements API	/pdf2	spike-api-statements-pdf2.openapi.json
Spike Statements API	/pdf2test	spike-api-statements-pdf2test.openapi.json

Postman

Postman (opens new window) has become the de-facto api documentation tool for REST-based APIs. As a definition system it lacks some of the expressive capabilities of OpenApi. However it has the advantage of providing both improved html docs as well as online tools which allow you to query the API. This tooling is useful for 2 reasons:

1. it allows developers to check whether a bug stems from the Spike API itself or from their implementation
2. it also allows non-developers to submit a request to the API

Here are the links to the Spike Postman workspaces:

Postman workspace
Spike Statements API Postman (opens new window)

You should also read our postman article for a number of tricks and techniques which will help you get the most out of our postman collections.

Swagger2

Swagger 2 (opens new window) is the older version of OpenApi. We include a Swagger2 definition for clients that use older tooling - notably Salesforce.

Note that Swagger 2 cannot fully describe all possible schemas for Spike endpoints - so partial definitions are used. See Swagger 2 limitations vs OpenApi 3 for more details.

Here are the links to the Spike Swagger 2 definitions:

Collection	Function	Swagger 2 definition
Spike Statements API	/pdf1	spike-api-statements-pdf1.swagger2.json
Spike Statements API	/pdf2	spike-api-statements-pdf2.swagger2.json
Spike Statements API	/pdf2test	spike-api-statements-pdf2test.swagger2.json

---

1. OpenApi differs from Postman - there is a definition file per-function whereas Postman has a definition for a collection of related functions. ↩︎