# API guidelines

The Pagero Web API is based on REST principles, where API resources are accessed through HTTPS requests, using the following HTTP verbs:

The base URL for the Pagero Online API is:

https://api.pageroonline.com/

The Pagero Online Web API consists of several “sub APIs”. The name of a sub API will always come right after the base URL:

https://api.pageroonline.com/{sub-API}/

Where {sub-API} is the name of the “sub API”, for example file, document, network etc.

The Pagero Web API uses URL versioning, which means that the API version is present in the URL. Each sub API is versioned individually, which means that the base URL including version for a sub API will be:

https://api.pageroonline.com/{sub-API}/{version}/

A media type describes the format of provided data, for example application/json or application/pdf.

In a request, the accepted media type should be put in the Accept header.

In a response, the media type of the response data will be included in the Content-Type header.

The Pagero Online Web API primarily uses the application/json media type for resource representations. However, other media types such as application/pdf, application/png etc. may also be appropriate for some resources.

If the client requests a media type that the API can not provide for a resource, the response code 406 (Not Acceptable) will be returned.

If the client provides data in a media type that the API does not accept, 415 (Unsupported Media Type) will be returned.

In some cases, the API may be able to return content using different media types (application/pdf, application/xml, etc.). In this case, the client should specify the requested media type through the Accept header.

The Accept header may contain a list of media types in priority order and the server will then use the first media type it supports in the response.

Resources are represented using JSON (JavaScript Object Notation), media type application/json.

JSON properties use camelcase notation.

In general there are two types of resources, instance resources and collection resources.

Resources that represent a collection are always in plural form.

• /documents

An instance resource is in most cases a collection resource, where a specific instance of the collection is pointed out by a resource identifier (path parameter).

• /documents/123

An instance resource may also exist without being part of a collection resource. In this case, the instance resource is expressed in singular form.

• /current-user

• /documents/123/presentation

Resource URIs should either use spinal-case (preferred) or lowercase.

In API specifications, path parameters should use camel case:

• /documents/{documentIdentifier}

There may be several different representations of a resource used throughout the API.

For example, different representations may be used for different operations, such that a GET operation returns one representation of a resource, while a PUT operation for the same resource may use another representation.

A resource is identified by its’ id.

The type of the id should be string, unless there’s a very good reason for using something else.

The format of the id may vary between different APIs and resources.

A resource id should be completely opaque to clients, meaning that clients should never make any assumptions about the structure of a resource id.

Timestamps should be formatted in UTC according to the ISO 8601 standard.

• 2021-07-10T18:02:24.343Z

All incoming timestamps and dates that follow the ISO 8601 standard should be accepted. Outgoing dates should be formatted like yyyy-mm-dd and timestamps should be formatted like yyyy-mm-ddThh:mm:ss.fffZ.

Properties that have a limited set of possible values that are not expected to change over time should be declared as enums. Important! Changing an enum available in a response message is considered a breaking change. Therefore, if the available enum values are expected to change over time, it's better to not define the property as an enum. The available values should then instead be available in the description and it should also be made clear that the available values may change over time.

Enum values should use PascalCase formatting, like this:

{
  "documentType": "OrderResponse"
}

A resource may have a reference to another resource. If the referenced resource is an instance resource, the reference can either consist of a simple id, like this:

{
  "userId": "123"
}

Or it can consist of a JSON object with a single ‘id’ property, which is the id of the referenced resource. This variant is often used in combination with resource expansion (see below).

{
  "user": {
      "id": "123"
  }
}

The expand query parameter can be used to include full versions of referenced resources directly in the response. The parameter should contain a comma-separated list of resource property names that should be fetched together with the requested resource.

For example, consider the following resource:

{
  "document": {
      "id": "123",
      "documentIdentifier": "45354",
      "creatingUser": {
          "id": "432"
      }
  }
}

The following request will retrieve the document resource, along with the referenced user:

GET /documents/123?expand=creatingUser

{
  "document": {
      "id": "123",
      "documentIdentifier": "45354",
      "creatingUser": {
          "id": "432",
          "username": "johndoe",
          "fullname": "John Doe",
          "...": "..."
      }
  }
}

Resource expansion can be used to avoid making unnecessary API requests when it’s known beforehand that a referenced resource will be needed.

A collection resource will often contain metadata that for example can be used for pagination. This metadata will then be available in the meta object.

This object has the following properties:

The actual collection items are available in a property called items. However, if the response contains no metadata, the collection items may be returned as a simple array.

GET /documents

{
    "meta": {
        "offset": 0,
        "limit": 25,
        "total": 43
    },
    "items": [
        {
          "id": "...",
          "...": "..."
        },
        {
          "id": "...",
          "...": "..."
        }
    ]
}

[
    {
      "id": "...",
      "...": "..."
    },
    {
      "id": "...",
      "...": "..."
    }
    
]

Query parameters should use camel case:

• /documents?searchTerm=foobar

A collection can be paginated using the offset and limit query parameters.

In general, the query parameter sort can be used for sorting on a specific property. The default sort order is ascending and by providing a “-” before the property name, the sort will be descending. The documentation for each resource provides information about which properties that are sortable and which property the collection is sorted on by default.

• sort=username
• sort=-createTime

If an error occurs, the API will reply with a response containing the appropriate HTTP status code in the 4xx or 5xx range, depending on whether it’s a client or a server error.

The response body will in general contain a single message with the following properties or an array of messages with the properties:

Below is a list of the most common HTTP response error codes that may be returned by the API.

All responses from the Pagero Web API will provide caching headers, which tell whether the response can be cached or not and for how long the response may be cached.

Below are a number of caching scenarios and their associated cache headers:

Some APIs may provide ETags in their responses. Clients should then utilize this in GET, PUT and POST requests in the following way.

Whenever a client sends a GET request to retrieve a resource, the ETag value of the resource should be provided in the If-None-Match header, if the resource has been previously fetched.

Browsers will in general handle this automatically.

The API will then compare the provided ETag with its’ own ETag, and if they are equal return a 304 Not Modified response.

Whenever a client sends a PUT requests to update a resource, the ETag value of the resource should be provided in the If-Match header.

The API will compare the provided ETag with it’s own ETag value for the resource. The resource will then be updated only if the ETags are the same.

If the ETags differ, the client’s version of the resource is outdated and a 412 Precondition failed response will be returned from the API.

When creating a new instance of a collection resource, it may be important that the collection has not been modified since it was fetched.

In some cases, the API may include an ETag when fetching a collection resource.

This ETag can then be provided in the If-Match header when sending a POST request to ensure that the collection has not been modified.

It’s important to maintain a consistent terminology for resource names across different APIs.

Here is a list of some common API resources: