FAQ

Working with REST APIs

Asseco REST APIs represent collection endpoints that serve the needs of banking applications. While each API exposes specific functionality, technical concerns of API usage have been designed in a consistent manner to enable easier integration into channel applications. This section describes concerns and usage patterns that are common to all APIs.

Authentication

API endpoints that require authentication expect an OAuth2 access token from client.

Before your client application can make API calls it must be registered to obtain its client-id and client-secret that will be used to identify client application itself and control access to APIs on per application basis. Registration process is completed manually by administrator and each application is granted permissions for minimal scope of APIs necessary for its function.

User facing client applications authenticate users (customers or agents) by following OpenID Connect protocol implemented by Authentication API.

APIs that call other APIs pass the original token they received in their backend requests.

To get access token client application follows one of the OpenID Connect flows with following endpoints hosted on Authentication API:

  • Authorize endpoint: As defined in OAuth2 framework, this endpoint performs authentication and authorization. Think of it as interacting with humans, it performs the login, consent, renders a UI, etc. Located at v1/authentication/connect/authorize.
  • Token endpoint: Again from OAuth2, this endpoint allows the requester to get an access token, an ID token and optionally a refresh token. If the authorize endpoint is human interaction, this endpoint is machine to machine interaction (it is a web API). Located at v1/authentication/connect/token.
  • UserInfo endpoint: New to OpenID Connect, this endpoint allows you to make a request using your access token to receive claims about the authenticated end-user. This user information could be included in the identity token, however this can cause bloat especially if we include things like profile pictures. Located at v1/authentication/connect/userinfo. Credentials from user are presented at OAuth 2.0 endpoint that issues a bearer token with preconfigured set of claims.
+--------+                                   +----------------+
| Client |                                   | Authentication |
|        |                                   |      API       |
|        |                                   |----------------|
|        |---------(1) AuthN Request-------->|                |
|        |  +--------+                       |                |
|        |  |        |                       |                |
|        |  |  End-  |<--(2) AuthN & AuthZ-->|   /authorize   |
|        |  |  User  |                       |   /token       |
|        |  |        |                       |                |
|        |  +--------+                       |                |
|        |                                   |                |
|        |<--------(3) AuthN Response--------|                |
|        |                                   |----------------|
|        |---------(4) UserInfo Request----->|                |
|        |                                   |   /userinfo    |
|        |<--------(5) UserInfo Response-----|                |
|        |                                   |                |
+--------+                                   +----------------+

Using Implicit and hybrid flow you can authenticate end user and client with one roundtrip to Authentication API:

  1. The Client sends a request to Authentication API /authorize endpoint.
  2. The Authentication API authenticates the End-User based on passed or entered credentials.
  3. The Authentication API responds with an ID Token and an Access Token.
  4. The Client can send a (optionally) request with the Access Token to the /userinfo endpoint.
  5. The /userinfo endpoint returns Claims about the End-User.

Response caching

Performance can be improved by the use of response caches. Optimizing the network using caching improves the overall quality-of-service in the following ways: reduces bandwidth, latency, load on servers and, also, hide network failures.

Cacheable API responses should use HTTP caching, which is part of the HTTP standard and described in full in RFC7234. HTTP caching is accomplished by adding HTTP headers to the responses that indicate how and for how long the resources can be cached.

Not every response is cacheable. Noncacheable responses should have no-cache value in Cache-Control response header parameter.

There are three different types of cache: client cache (on client side), gateway cache (on server side) and proxy cache (cache on network). Caches can be shared or private. A shared cache is a cache that stores responses to be reused by more than one user. A private cache, in contrast, is dedicated to a single user. If the response can be cached in either shared or private cache, Cache-Control response header parameter should include public directive. If only private cache may store and reuse response, Cache-Control response header parameter should include private directive

In a case where a response may be different based on the value of one or more request headers the Vary header in HTTP caching is used to indicate that. When a server includes a Vary header in its response, it is indicating that the response may vary based on the value of the header(s) specified in the header.

For example, if a server returns a response with a Vary header that lists Accept-Encoding, it is telling caches that the response may be different depending on the encoding that the client can accept. If a cache has a cached response that includes a Vary header, it cannot use that cached response to satisfy a subsequent request unless the request headers match exactly those listed in the Vary header. In other words, if a cache has a response that varies by the Accept-Encoding header, it cannot use that response to satisfy a request with a different encoding.

The Vary header is particularly useful in scenarios where a server may return different responses based on device type, user agent, language preferences, or other factors that may be included in the request headers. By including a Vary header in the response, the server can ensure that caches do not serve stale or incorrect responses to subsequent requests.

Expiration-based caching

Expiration-based caching involves setting an expiration time for the cached resource, after which the client or intermediary server must revalidate the resource with the original source. The expiration time should be specified in the response headers using the Cache-Control header. (Expires header should not be used).

The Cache-Control header specifies a variety of directives that control caching behavior, including the maximum age of a cached response. The directive max-age specifies the maximum number of seconds that a response can be cached, while the s-maxage directive specifies the maximum age of a response for shared caches.

An example of how the Cache-Control header might look:

Cache-Control: max-age=86400, s-maxage=3600

In the example the header tells the client or intermediary server to cache the response for a maximum of 86400 seconds (1 day), and to cache the response for shared caches (such as intermediary servers) for a maximum of 3600 seconds (1 hour).

If the cache is implemented and the response is served from the cache, such response should have Age header parameter which contains an estimate of the amount of time in seconds since the response was generated or successfully validated at the origin server.

Cache-Control: max-age=3600
Age: 100

In the example the header states that the response has been served from cache. The response is not stale because the response was generated by an origin server a 100 seconds ago (as illustrated on the diagram bellow)

    +-------------+                                    +--------------+                                    +--------------+
    |             |        Request for resource A      |              |        Request for resource A      |              |
    |             | ---------------------------------> |              | ---------------------------------> |              |
    |             |                                    |              |                                    |              |
    |             |  Response with expiration headers  |              |  Response with expiration headers  |              |
    |             | <-----------HTTP 200-------------  |              | <-------------HTTP 200-----------  |              |
    |             |    (Cache-Control: max-age=3600)   |              |    (Cache-Control: max-age=3600)   |              |
    |             |                                    |              |                                    |              |
    |   Client    |                                    |     Cache    |                                    |   Server     |
    |             |                                    |              |                                    |              |
    |             |        Request for resource A      |              |                                    |              |
    |             | ---------------------------------> |              |                                    |              |
    |             |                                    |              |                                    |              |
    |             |  Response with expiration headers  |              |                                    |              |
    |             | <-----------HTTP 200-------------  |              |                                    |              |
    |             |    (Cache-Control: max-age=3600)   |              |                                    |              |
    |             |             (Age: 100)             |              |                                    |              |
    |             |                                    |              |                                    |              |
    +-------------+                                    +--------------+                                    +--------------+

Validation-based caching

Validation-based caching is a technique used by HTTP caches to ensure that cached responses remain fresh and up-to-date. Unlike expiration-based caching, where a cached response is considered fresh based on its age or expiration time, validation-based caching relies on revalidating cached responses with the origin server before serving them to clients.

To validate responses in cache validators are used. There are two types of validators, strong validators and weak validators. A strong validator changes if the body or headers of the response change. A weak validator might not change for every change to the response data and headers. It's up to the server to decide when a change is warranted. For example, only significant changes are validated and validation is successful when less significant aspects change.

To facilitate validation-based caching, HTTP caching provides cache control headers that can be used to specify under what conditions it should be considered fresh or stale. These headers include:

ETag header provides a unique identifier for a resource, which can be used to validate cached responses. When a cache receives a conditional request for a resource, it includes the ETag in the request headers. If the resource on the origin server has the same ETag as the cached response, the origin server returns a "304 Not Modified" response. The ETagconcept is the typical example of a strong validator

Last-Modified header indicates the time at which the resource was last modified on the origin server. When a cache receives a conditional request for a resource, it includes the Last-Modified time in the request headers. If the resource on the origin server has been modified since the cached response was last retrieved, the origin server returns a new version of the resource. The Last-Modified concept is the typical example of a weak validator

Validation based caching workflow:

  • The client sends a request for a resource. The request hits the cache. There's no cached version of the response available, so the cache forwards the request to the API server. The server returns a response that includes an ETag and Last‑Modified header to the cache, which forwards response to the consuming application, and, at the same time, stores a copy of the response. For any subsequent request if the cached response is fresh (i.e., it has not expired or been invalidated), the cache returns the cached response to the client as illustrated.
    +-------------+                                    +--------------+                                    +--------------+
    |             |        Request for resource A      |              |        Request for resource A      |              |
    |             | ---------------------------------> |              | ---------------------------------> |              |
    |             |                                    |              |                                    |              |
    |             |  Response with expiration headers  |              |  Response with expiration headers  |              |
    |             | <-----------HTTP 200-------------  |              | <-------------HTTP 200-----------  |              |
    |             |    (Cache-Control: max-age=3600)   |              |    (Cache-Control: max-age=3600)   |              |
    |             |        (ETag: "1234567890")        |              |        (ETag: "1234567890")        |              |
    |   Client    | (Last-Modified: Wed, 21 Oct 2015   |     Cache    | (Last-Modified: Wed, 21 Oct 2015   |   Server     |
    |             |           07:28:00 GMT)            |              |           07:28:00 GMT)            |              |
    |             |                                    |              |                                    |              |
    |             |        Request for resource A      |              |                                    |              |
    |             | ---------------------------------> |              |                                    |              |
    |             |                                    |              |                                    |              |
    |             |  Response with expiration headers  |              |                                    |              |
    |             | <-----------HTTP 200-------------  |              |                                    |              |
    |             |    (Cache-Control: max-age=3600)   |              |                                    |              |
    |             |             (Age: 100)             |              |                                    |              |
    |             |        (ETag: "1234567890")        |              |                                    |              |
    |             | (Last-Modified: Wed, 21 Oct 2015   |              |                                    |              |
    |             |           07:28:00 GMT)            |              |                                    |              |
    +-------------+                                    +--------------+                                    +--------------+
  • When the request is made and the cached response is stale (i.e., it has expired or been invalidated), the cache sends a conditional request to the origin server to check whether the resource has been updated since the cached response was last retrieved. To make a conditional request the If-None-Match and If-Modified-Since headers are used in HTTP requests. The If-None-Match header is used to request a resource only if it has a different ETag value than the one provided in the header. The If-Modified-Since header is used to request a resource only if it has been modified since the date provided in the header Last-Modified. If the origin server returns a 304 Not Modified response, indicating that the resource has not been updated, the cache returns the cached response to the client.
    +-------------+                                    +--------------+                                    +--------------+
    |             |        Request for resource A      |              |        Request for resource A      |              |
    |             | ---------------------------------> |              | ---------------------------------> |              |
    |             |                                    |              |   (If-None-Match: "1234567890")    |              |
    |             |                                    |              |(If-Modified-Since: Wed, 21 Oct 2015|              |
    |             |                                    |              |            07:28:00 GMT)           |              |
    |             |                                    |              |                                    |              |
    |             |  Response with expiration headers  |              |               Response             |              |
    |   Client    | <-----------HTTP 200-------------  |    Cache     | <-------------HTTP 304-----------  |    Server    |
    |             |        (ETag: "1234567890")        |              |             Not Modified           |              |
    |             | (Last-Modified: Wed, 21 Oct 2015   |              |                                    |              |
    |             |           07:28:00 GMT)            |              |                                    |              |
    |             |                                    |              |                                    |              |
    |             |                                    |              |                                    |              |
    +-------------+                                    +--------------+                                    +--------------+
  • If the origin server returns a new version of the resource (i.e., a "200 OK" response with a new version of the resource), the cache replaces the cached version with the new version and returns the new version to the client.
    +-------------+                                    +--------------+                                    +--------------+
    |             |        Request for resource A      |              |        Request for resource A      |              |
    |             | ---------------------------------> |              | ---------------------------------> |              |
    |             |                                    |              |   (If-None-Match: "1234567890")    |              |
    |             |                                    |              |(If-Modified-Since: Wed, 21 Oct 2015|              |
    |             |                                    |              |            07:28:00 GMT)           |              |
    |             |                                    |              |                                    |              |
    |             |             Response               |              |               Response             |              |
    |   Client    | <-----------HTTP 200-------------  |    Cache     | <-------------HTTP 200-----------  |    Server    |
    |             |    (Cache-Control: max-age=3600)   |              |    (Cache-Control: max-age=3600)   |              |
    |             |        (ETag: "1234567891")        |              |        (ETag: "1234567891")        |              |
    |             | (Last-Modified: Wed, 25 Oct 2015   |              | (Last-Modified: Wed, 25 Oct 2015   |              |
    |             |           09:25:00 GMT)            |              |           09:25:00 GMT)            |              |
    |             |                                    |              |                                    |              |
    +-------------+                                    +--------------+                                    +--------------+

Versioning

Each API has multiple versions available to access at any one time. Each API is versioned independently as it evolves through major versions. Backward compatible changes such as adding additional elements, endpoints are not versioned.

Version label is an opaque string placed in URI just before API basepath. Examples:

       <---- host -----><ver><-- basepath -->
http://api.server-01.com/v1/correspondence/
http://api.server-01.com/v2/correspondence/
http://api.server-01.com/v1/location/
http://api.server-01.com/v1beta/location/

Interface stability

Our banking APIs support wide variety of scenarios with resources and methods as interfaces. Some of these interfaces are standard and very stable. Others offer new functionality that is continuing to evolve.

We realize that you invest in these interfaces, and therefore must know when and how we expect them to change. For that reason, we define interface stability labels and uses these in definitions of API methods.

Label Meaning
Stable This documented interface is expected to undergo only backwards-compatible changes between major releases. Once we release new major version we are still supporting a previous major version for a period of one year.
Evolving This documented interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in between major releases. Changes are announced as documentation updates 90 days before API releases.
Deprecated This interface is deprecated and likely to be removed in a future release. For previously stable interfaces, the change was likely announced in a previous release. Deprecated interfaces will be removed from our APIs.

Backward compatibility policy for stable APIs

Different changes of APIs can have different impact on your client. Your implementation of client code should tolerate backward compatible changes and handle breaking changes gracefully.

Change area Backward compatible change (documentation update) Breaking change (release of new major version)
Resources (collection, singleton) New resource, sub-resource, command, representation; Moving resource to new URI with redirection from previous Removing existing resource without redirection; Removing existing operation
Resource URIs and verbs New URI template and endpoint Changing URI path template; Adding mandatory query argument; Renaming existing query argument; Changing the type of existing argument; Changing HTTP verb
Command and resource models Adding optional field; Changing the order of existing fields; Making mandatory field optional Adding mandatory field; Renaming existing field; Changing type of existing field; Changing the placement of existing field in representation structure; Removing existing field
Problems Introducing new problem code Changing the meaning of existing problem code
Validations Introducing new command field or URI argument validation rule with warning severity Changing existing validation rule to be more tolerant than before; Removing existing validation rule; Introducing new command field or URI argument validation rule with error severity; Changing existing validation rule to be more strict than before
Enumerations New enumeration; New enumeration literal; Changing descriptions or translations Removing enumeration literal; Forcing enumeration on previously unrestricted field
Classifications New classification; New classification value; Removing classification value; Changing descriptions or translations; Renaming classification literal Forcing classification on previously unrestricted field

Enumerations and classifications

String parameters and fields in API contracts can be restricted to predefined list of acceptable literals and codes. Enumerations represent closed set of values that developers who consume API can refer to in their implementation and expect to be stable across different implementations. Classifications, on the other hand, are open set of values that may be extended and changed over time and across different implementations. Developers referring to specific classification literals in their code must expect changes over time and across different implementations. Enumeration values are part of contract, while classification values are not.

By convention name of enumeration or classification is plural as it describes set of values. Literal name is in kebab case, while title is in title case. For example, classification with title: Transaction Codes by convention has literal name transaction-codes. Enumerations values are explained with literal and description, while classification values also have optional short mnemonic or numeric code that uniquely identifies classification value.

Error handling

Requests made to our APIs can result in a number of different error responses, and there are a few basic recovery tactics. The following topic describes the recovery tactics, and provides a list of error values with a map to the most common recovery tactic to use. Error is always indicated with standard 4xx and 5xx http status codes. With status code 400 we return more details on validation errors, while with status code 440 we return more details on specific business rules that were violated by request.

Common http status codes used across APIs

status code when used
401 Not authorized Used to indicate that request must be authenticated but valid access token was not supplied
403 Forbidden Used to indicate that access to API is not allowed, even though the request was authenticated with valid access token.
404 Not found Used to indicated that there are no resources that match the request. For GET request that fetch single resource based on identifiers supplied in path this means that resource with such identifier was not found. For POST, PUT, PATCH, DELETE requests that send commands at identified resource this means that resource with such identifier was not found. When GET request issued on collection resource filters data with query parameters and response is empty list 200 OK should be used with response payload representing empty list
500 Internal error Used to indicate that API implementation encountered an unexpected condition which prevented it from fulfilling the request.
503 Not implemented Used to indicate that API implementation does not yet support the functionality of a documented method.

400 - Validation errors

When request fails server validation, response contains list of validation errors for each invalid field. Validation error is uniquely identified by its literal and is not specific to APIs.

Example validation problem payload (json):

{
  "errors": [
    {
      "tag": "phone-number",
      "error": "invalid-format",
      "message": "Format for this field is invalid"
    },
    {
      "tag": "phone-number",
      "error": "max-length",
      "message": "Content exceeds maximum alowed length"
    },
    {
      "tag": "account-number",
      "error": "check-digit-invalid",
      "message": "Check digit is invalid for this field"
    }
  ]
}

Elements of validation problem model:

Property Name Type/Format Description
errors[] array of object List of validation errors
errors[].tag string Name of input element (field or parameter) that is in invalid. If missing or null it is interpreted that validation error refers to entire request rather than to specific element
errors[].error string Unique literal that identifies validation error
errors[].message string MMessage that explains failed validation

Validation errors:

Validation error literal Description
max-length Value supplied exceeds maximum allowed length
min-length Value supplied does not meet minimum length
required Mandatory field or parameter was not supplied
out-of-range Value supplied was out of allowed range
invalid-format Value supplied does not have expected format
unknown-enum Value supplied does not belong to enumeration
not-on-list Value supplied does not belong to classification
check-digit-invalid Value supplied does not conform to check digit validation
combination-required Parameter must be used with other parameters that were not supplied
read-only Parameter is read-only

440 - Business problem

Business problems may be returned for request with verbs that affect state (POST, PUT, PATCH, DELETE) in situations when request is formally valid, business rule or policy does not allow processing and none of the standard HTTP status codes explains the situation well enough.

Each problem is uniquely identified by stable literal and numeric code that is used to map to backend system implementations. APIs document their domain specific problems in a Problems page of their documentation. In documentation for specific API request, when 440 response is possible, documentation lists possible problems.

Example problem payload (json):

{
  "problem": "document-locked",
  "message": "Document you are trying to manipulate is locked by another user.",
  "details": "User john.doe has locked the document."
}

Elements of problem model:

Property Name Type/Format Description
problem string Unique literal that identifies specific problem
message string Message explaining the situation and optionally remedies
details string Optional details supplied for troubleshooting

Idempotent command processing

HTTP does not guarantee reliable message delivery so in the presence of timeouts and broken network connections only strategy for client to assure processing of a request is to repeat submission. Semantics of HTTP verbs such as GET, PUT, PATCH, DELETE is naturally idempotent in a sense that repeated request would not result in adverse effects. HTTP POST is used to create new resources which is not idempotent and perform resource specific actions that may or may not be idempotent. Some commands submitted using POST verb require special handling in order to detect repeated command submission and avoid duplicate processing. Endpoints marked as idempotent will assure idempotent command processing if command can be reliably identified as unique from the perspective of instructing party. For example, POST /balance-transfers endpoint will use instruction-id field in balance-transfer instruction to detect repeated submissions. API implementations are responsible to assure reliable detection of repeated commands during a reasonable time period such as 7 days.

Events

Events are used to publish the fact that something happened to interested subscribers. Each API specifies events published and their payload in Events page. Events contain minimal payload that describes what happened and triggers subscriber processing. Subscriber is expected to get any additional information that may be needed in a "push to pull" manner.

All event definitions are compliant with Cloud event specification so interoperability across services, platforms and systems can be achieved.

Events will contain two types of information: Context metadata providing contextual information about the event occurrence and the Event Data containing domain-specific information about the event occurrence (i.e. the payload).

Context can be serialized independent of the event data, providing that context attributes can be inspected at destination without deserializing data payload. All events inherit definition from shared event base object which contains all context attributes.

Standard context attributes are:

  • specversion: The version of the CloudEvents specification that the event uses.
  • type: Type of event should have following format: ... (example: asee.current-account.account.debited)
  • source: Identifies the context in which an event happened. Source should have following format [/tenants//system/]//. For multitenant implementation /tenants/ part of the source should be specified, otherwise it should be omitted (example: pub/current-account/current-accounts)
  • id: Identifies the event. Combination source + id is unique for each distinct event.
  • subject: Subject of the event in the context of the event producer should be the event occurrence source ID
  • time: The timestamp of when the event occurred.

Extension context attributes are:

  • traceparent: Only used for distributed tracing purposes. Contains a version, trace ID, span ID, and trace options
  • tracestate: Only used for distributed tracing purposes. Comma delimited list of key-value vendor-specific trace pairs
  • sequence: Only used in case of a group of multiple related events. Value expressing the relative order of the event.

These attributes, while descriptive of the event, are designed such that they can be serialized independent of the event data. This allows for them to be inspected at the destination without having to deserialize the event data.

Events are transported from a source to a destination via messages. Messages can be delivered through various industry standard protocol (e.g. HTTP, AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor specific protocols (AWS Kinesis, Azure Event Grid). A protocol binding describes how events are sent and received over a given protocol. For more information about Cloud event protocol binding take a look at Cloud event specification protocol bindings

Any kind of event implementation can have additional properties not explicitly defined by standard definition. Additional properties should start with prefix x-. Here is an example of an event instance with additional properties implemented:

{
  "specversion": "1.0",
  "type": "asee.device.issued-devices.payment-card.replaced",
  "source": "bapo/device/issued-devices/payment-cards",
  "id": "7e5108d7-247b-4763-b35f-2ccf3bed54e7",
  "time": "2022-04-05T17:41:00Z",
  "subject": "4513256858760869",
  "data": {
    "account-number": "105100000000082426",
    "customer-number": "2306985757916",
    "arrangement-number": "105100000000082426",
    "old-device-id": "2333423",
    "new-device-id": "2333897",
    "old-card-number": "4513256858760869",
    "new-card-number": "6250941006528599",
    "old-expiration-date": "03-22",
    "new-expiration-date": "03-25",
    "x-product-code": "MST0223",
    "x-card-holder": "0907895675432",
  }
}

Synchronization

When there is a need for some resource collection to have synchronization capabilities, usually to provide alternative data storage to existing one, for performance or other similar requirements, that API resource provides incremental synchronization mechanisms.

There are two distinct delivery styles for the data synchronization that are supported:

  • Synchronous via REST API, with separate GET method with /sync suffix
  • Async style via events delivered trough some queue as change happens.

Sync REST API endpoint provides consumers with sync-timestamp, for each resource object, as a additional property, which can be used as query parameter for additional API requests, which will filter only collection items that were added, changed or deleted since point in time represented by that timestamp. API consumer is responsible to keep track of latest synchronization timestamp processed for specific collection. Synchronization timestamp named sync-timestamp is a string representing timestamp, preferably in one particular format, illustrated in the example below. It is guarantied that this time stamp can only increase as time passes that can have any format as long as it is guaranteed to be monotonically increasing with every change. Example value for sync timestamp: 0x00000004156E07CB If some resource collection has good reason to depart with timestamp format from the recommended one, it must to be explicitly documented in API definition. This timestamp is used for the process of synchronization to mark the time point for which records are already synched (their last update was older than this timestamp)

Apart from this, Sync REST API SHOULD provide following headers in the response: X-Sync-Timestamp, X-Chunk-size with usual semantics and X-Total-Sync-Count which represents total number of records left for synchronization, for given timestamp provided in the request.

Async Events are optional and alternative mechanism to keep resources data in sync, where it deliver CRUD changes of any object in a resource collection, one at the time. Usually, API consumer would first use REST API /sync method to sift through resource collection until whole collection is synchronized, than it can rely on those events to deliver any upcoming change. Event must carry whole object that is of interest for synchronization, equivalent to its representation in REST API /sync method, without need for additional data collection on consumer side. Sync event also needs to have sync-timestamp property of same type in it's header.

Bulk optimizations

When API endpoint is optimized for bulk reads and bulk writes you can expect that their payload contract is flattened, default content type to be text/csv and http compression to be used by default. This minimizes network traffic and simplifies processing at other end.

Commonly used string formats

Date and time

For point in time values we use date-time defined by RFC3339, and date format defined by RFC3339 as full-date.

Here are some examples of well formatted date and date-time:

1985-04-12                This `date` represents April 12th, 1985
1985-04-12T23:20:50.52    This represents 20 min and 50.52 sec after 23h on April 12th, 1985 in local time
1996-12-19T16:39:57+01:00 This represents 39 min and 57 sec after 16h on December 19th, 1996 (CET)
1985-04-12T23:20:50.52Z   This represents 20 min and 50.52 sec after 23h on April 12th, 1985 in UTC

Format specified in RFC3339:

   date-fullyear   = 4DIGIT
   date-month      = 2DIGIT  ; 01-12
   date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on
                             ; month/year
   time-hour       = 2DIGIT  ; 00-23
   time-minute     = 2DIGIT  ; 00-59
   time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second
                             ; rules
   time-secfrac    = "." 1*DIGIT
   time-numoffset  = ("+" / "-") time-hour ":" time-minute
   time-offset     = "Z" / time-numoffset

   partial-time    = time-hour ":" time-minute ":" time-second
                     [time-secfrac]
   full-date       = date-fullyear "-" date-month "-" date-mday
   full-time       = partial-time time-offset

   date-time       = full-date "T" full-time

Currency code

For currency codes we use 3 letter code from ISO 4217. Examples are USD, GBP, CHF

Country code

For country codes we use 2 letter code from ISO 3166-1. Examples are US, UK, CH

Commonly used query parameters

Pagination

When a collection resource supports pagination of results you can supply pagination control parameters and expect pagination related fields in response payload.

GET correspondence/communications?page=1&page-size=5 HTTP/1.1
Parameter Type/Format Description
page integer One based index of the page to return. Default index 1 s used when parameter is not supplied
page-size integer Number of items to return on a page. Default size 10 is used when parameter is not supplied 
{
    "page": "1",
    "page-size": "5",
    "total-count": "123",
    "total-pages": "21",
    ...
}

Chunking

When a collection resource supports chunking of results, API client can supply chunking control parameters and expect chunking related headers in response.

GET arrangements/sync?chunk=2&chunk-size=5 HTTP/1.1
Parameter Type/Format Description
chunk integer The index of the chunk to return. Default index 1 s used when parameter is not supplied
chunk-size integer Number of items to return on a page. Default size 10 is used when parameter is not supplied

Sorting

When a collection endpoint supports sorting of results you can supply sorting control parameters sort-by and sort-order and expect a sort related fields in the sorted response payload.

GET correspondence/communications?sort-by=status&sort-order=desc HTTP/1.1

{
    "sort-order": "desc",
    "sort-by": "status",
    ...
}
Parameter Type/Format Description
sort-by string Name of the response field to sort by. Field must be supplied on lowercase dash naming convention
sort-order string enum: asc, desc Ascending or descending order. Default order asc is used when parameter is not supplied

Shaping

When an endpoint supports shaping of responses to GET requests you can supply shaping control query parameters trim and include and expect only specified set of fields in the response payload. If you do not specify fields to include or trim, response will contain fields returned by default according to reference documentation. You can remove default set of returned fields by using trim=* and then add only fields you need with include. Reverse also applies so you can start from full set of fields with include=* and then remove only fields you don't need with trim.

If endpoint supports shaping, scalar fields in a response model object are returned by default while nested objects and arrays are returned according to sensible defaults specified in documentation.

GET location/facilities?kind=atm&trim=*&include=id,coordinates HTTP/1.1
Parameter Type/Format Description
trim string format:csv Comma separated list of fields to trim from response. Field names must be supplied on lowercase dash naming convention. Nested fields are accessed with dot notation.
include string format:csv Comma separated list of fields to include in response. Field names must be supplied on lowercase dash naming convention. Nested fields are accessed with dot notation.

Synchronization parameters

When a collection resource supports incremental synchronization you can supply sync-timestamp as query parameter and expect only collection items that were added, changed or deleted since point in time represented by timestamp. Each collection item will have a sync-timestamp field so API consumer is responsible to keep track of latest synchronization timestamp processed for specific collection.

Filtering

Many collection resources accept a list of predefined optional query parameters that filter returned results. Parameters are combined with a logical AND. Unless otherwise specified parameters that filter text will assume case-insensitive match. When parameter contains multiple values, unless otherwise specified, result is matched on any of the supplied values.

GET correspondence/communications?contact-medium=sms&status=delivered HTTP/1.1

Searching

Some collection endpoints enable expression based search queries.

GET party-data/individuals?q=John+Doe HTTP/1.1