API Conventions

Neon is a JSON-based Web API organized around resource-oriented URLs.

The API generally follows these rules:

  • The URL path is always lowercase.
  • Kebab case is used for multiple words (e.g. /line-items/).
  • Resources are named using plural nouns, e.g. /orders/.
  • A path such as /orders/ returns a list of orders and /orders/:id returns a specific order.
  • Nested resources are supported, such as /orders/:id/line-items/:id
  • Field names and URL parameters use camelCase, E.g. ?lineItemId=123
  • If a URL param accepts multiple values, we use the plural form and accept a comma-separated list, like so: ?userIds=1,2,3
Common Response Body Formats

Response body containing a single object:

    field: "value"
Response body containing a list of objects:

    results: [{field: "value"},{field: "value"}], 
    continuationToken: ""
Responses may optionally include page, pageSize, and count fields in some cases. If the continuationToken is null, you are at the end of the list.

    results: [{name: "a"},{name: "b"}]
    continuationToken: "",
    page: 1,
    pageSize: 25,
    count: 100
Standard error response body (e.g. Status codes: 400 and 500):

    errors: ["Error message 1", "Error message 2"]
HTTP Verbs
HTTP Verb Purpose Typical Response Code(s)
HEAD Returns HTTP headers for a GET request 200
GET Read data 200
POST Create 201
PUT Replace entire record 204 or 200
PATCH Partial Update 204 or 200
DELETE Delete 204
HTTP Response Codes
Code Notes
201 Created POST
204 No Content PUT, PATCH, DELETE
301 Moved Permanently
302 Moved temporarily
400 Bad Request Used instead of 422 when request body contains invalid data (e.g. missing required fields). See above for error response body format.
401 Unauthorized
403 Forbidden
404 Not Found Used for unknown paths or unsupported verbs for known paths
409 Conflict
429 Too Many Requests
500 Internal Server Error See above for error response body format.