Calling the API

Once your web or mobile app has a valid access token, that token can be used to call any endpoint within the globaliD APIs that has a scope covered by that access token. To call the API, you must embed the access token in the HTTP request header, like this:

__BEARER <access_token>__

Where an API endpoint requires additional parameters that aren't included in the URI itself, those parameters are passed in the body of the HTTP request using JSON format. For example:

    POST /v1/identities/<gid_uuid>/updates
    BEARER <access_token>

  {
    display_name: "John Smith"
  }

In this example, the display_name parameter was passed in as part of the request body, while the UUID of the identity to be updated was included in the URI itself, as <gid_uuid>.

The globaliD API endpoints all follow standard RESTful principles, identifying the resource in the URI itself, using standard HTTP methods for adding, updating, deleting and retrieving resources, and using the returned HTTP status code to indicate the results of the operation.

Most API endpoints will return either 200 (OK) or 201 (Accepted) when the call was successful. Nonexistent endpoints will return a 404 (Not Found) error, while missing parameters or headers will return a 400 (Bad Request) error. If you are not authorised to access the endpoint, the API will return either 401 (Unauthorised) or 403 (Forbidden).

In addition to the status code, if an error is returned the body of the response will contain more information about the error in JSON format. For example:

    HTTP/1.1 401 Unauthorized

    {
      statusCode: 401,
      message: "You are not authorized to access this resource"
    }

If the API call succeeded, the response will generally be empty if no additional information was to be returned -- the status code itself indicates the success or failure of the operation. Where an endpoint returns additional information, that information will be included in the body of the response, again in JSON format. For example:

Request:

    GET /v1/identities/me
    BEARER <access_token>

Response:

    HTTP/1.1 200 OK

    {
      "gid_uuid": "d58f094f-6d28-4aa1-9bf9-afe517c396b9",
      "gid_name": "jsmith",
      "type": "individual",
      "status": "in_use",
      "created_at": "2019-04-03t21:19:12z",
      "released_at": null,
      "completed": true,
      "public_signing_key": "...",
      "public_encryption_key": "...",
      "purpose_personal": false,
      "purpose_professional": true,
      "purpose_recreational": false,
      "display_name": "John Smith",
      "description": "Professional carpenter based in San Jose, CA",
      "display_image_url": "...",
      "region_code": "NM",
      "region_name": "North America",
      "country_code": "USA",
      "country_name": "United States",
      "state_code": "USA-CA",
      "state_name": "California",
      "metro_code": "USA-CA-SFO",
      "metro_name": "San Francisco"
    }

Every API endpoint is documented, describing the endpoint's purpose, what parameters it expects, which types of access tokens are allowed to call the endpoint, what HTTP status values it can return, and what data (if any) it returns if the call succeeded.

For information on what you can do with the various API endpoints, please refer to the following section in the documentation. A comprehensive reference of all API endpoints supported by globaliD can also be found ::here::.