Conventions

These are the conventions that CostQuest targets when developing APIs. There may be exceptions to these, thus they are not codified as a true standard.

Base URL

The appropriate URL to use for developing with CostQuest APIs is https://api.costquest.com.

API Names

  • APIs and operations are named in lowercase.

  • Create, Read (Get, List), Update, Delete (CRUD) operation prefixes will be used for operations that manage items. Examples of managed items include accounts and keys.
    • create will be the prefix used for operations that generate a new item.
    • Read will be split into two prefixes
      • get will be used for a read operation that is for a single item.
      • list will be used for a read operation that is for multiple items.
    • update will be the prefix used for operations that modify an existing item.
    • delete will be the prefix used for operations that remove an existing item.
  • For APIs that perform computational analysis, usage of a single verb is acceptable. Examples include collect or divide.
    • For cases where a single verb is inadequate, additional detail may be included after the verb.
  • For APIs that require no CRUD operations, there are no prefix requirements.
  • For APIs that provide support for multiple HTTP methods (GET for single record, and POST for multiple) they will be named without a read prefix of get or list and use only a verb, noun, or combination thereof.

API Versioning

To avoid breaking implementations using existing APIs, if there are breaking changes that will be introduced, a new version of the API will be created. Newer versions of APIs will receive a number after their name starting with a “2” and increasing. For example, the coverage API does not follow the conventions outlined in this document as of February 25, 2025. If this API is modified and the changes are breaking, a new coverage2 API will be published. CostQuest will determine a sunset schedule for old APIs and communicate with users granted access to them to inform them if the API is to be sunset. In some cases, legacy APIs may persist for years. These requirements also apply to individual endpoints.

If API changes are non-breaking and continue to return the same responses for the same requests as their prior version, APIs will not receive a name change.

URL Conventions

Route parameters are used to construct more logical API URLs and are used to force decisions on parameters (Example: vintage of data) that change infrequently or affect the type of response given. For example, The fabric/data API includes both route and query parameters: fabric/{vintage}/data/{layer}[?uuid] The vintage parameter is of high importance, and the layer parameter indicates a request for a specific type of data, whereas the uuid query parameter defines an item to retrieve data for.

HTTP Methods

  • GET
    • Used whenever possible and applicable. This allows for effective caching.
  • POST
    • Used for creating items, updating items, and making requests that require large payloads such as those requiring GeoJSON as input.
  • DELETE
    • Used for removing items.

HTTP Status Codes in Responses

This is not an exhaustive list of HTTP status codes. These represent the most commonly encountered codes users will experience in the CostQuest APIs implementation.

  • 200 is the common response for successful requests.
  • 201 is used when creating new items.
  • 400 is used to identify a bad request typically via malformed data or missing parameters.
  • 401 is used when an unauthenticated request is made. Typically indicates missing or invalid credentials.
  • 403 is used when an account is authenticated but not authorized to access the requested resource. An instance where this status code is returned is when an account exceeds its quota. The message value in the response provides more detail.
  • 404 is used then a requested resource was not found or unavailable.
  • 408 is used when a request is taking too long to complete.
  • 429 is used when an account has made too many requests and is being throttled. A Retry-After header provides the wait time in seconds until the rate limiting is lifted.
  • 500 is used when backend processing failed or an exception was uncaught.
  • 502, 503 and others in the 500 series indicate service or infrastructure level issues such as brief periods of scheduled downtime or upgrades.

Request and Response Structures

  • Payloads and responses are always in JSON (application/json) unless explicitly noted otherwise. An example of an exception would be binary data such as vector tiles.

  • APIs that provide continuations will be returned in a format resembling

    {
    "maxcount": 5000,
    "locationcount": 10,
    "query": {},
    "data": [],
    "continuations": [],
    "message": "ok",
    "statusCode": 200
}

  • For APIs that create items, the response will include a unique identifier or reference relevant to the item created. For example, when creating an API key, the response includes the created key.

    {
    "apikey": "<apikey>",
    "message": "apikey created",
    "statusCode": 201
}

  • In the event of errors, the response will include JSON that indicates the set HTTP status code as well as a message that will help users diagnose the source of the error.

    {
    "statusCode": 401,
    "message":"no apikey or Authorization header"
}