Getting Started #

Accessing the API #

The API is available at https://<host>/v4_server/external/v1/. Available endpoints and their payloads are documented via OpenAPI: [https://docs.citywidesolutions.com/viewer/?urls.primaryName=MM].

For brevity, all endpoints assume a base of https://<host>/v4_server/external/v1. <host> must be replaced with the appropriate domain name of the environment you wish to interact with.

Example: https://demo.citywidesolutions.com/v4_server/external/v1.

HTTPS is always required to connect to the API.

Environments #

Domain	Environment
https://demo.citywidesolutions.com/	Demo
https://v4.citywidesolutions.com/	Production

Authorization #

API keys can be generated by administrators through the Users section of the application. API keys are tied to an existing user account and share the permissions relating to the roles that user is assigned to.

To authenticate:

POST /authenticate
Content-Type: application/json

{
    "api_key": "<api key>",
    "client_db": "<client db>",
    "username": "<user name>"
}

Parameter	Description
`api_key`	The API key related to the user accessing the resource.
`client_db`	A string containing your short-form client name (used during login) and schema (database instance) code separated by a period, eg. `works_tst.main`.
`username`	Name of the user associated with the provided API key.

Rate limiting #

Calls to the various API endpoints are rate limited: a maximum number of requests is allowed for a given time period or window. A new window begins when a request is received and there is no currently active window.

Rate limiting follows the draft specification as closely as possible.

The following headers are returned for all rate limited calls:

Header	Description
`X-RateLimit-Limit`	Total number of allowable requests for a window.
`X-RateLimit-Remaining`	Number of requests left within the current window.
`X-RateLimit-Reset`	Number of seconds left before current window expires.