Paths and Resources

This section provides details on resources and fields and provides the associated naming conventions and standards.

• Introduction
• Paths
• Resources
  • Be Consistent
  • Prefer Single Root Resource
  • Defining Sub-Resources
  • Defining Resources with Non-Unique Identifiers
  • Defining Resource Actions
• Resource Identifiers
• Standards for Paths and Resources

Introduction

A REST API’s path consists of an HTTP method, a base path and one or more resources and identifiers.

The key abstraction of information in REST is a resource. A resource is a concrete concept related to the business domain e.g. accounts. Any information that can be named as a noun can be a resource, for example, a REST resource can be a document or image, a temporal service, a collection of other resources, or a non-virtual object e.g. a person. REST resources are typically plural nouns e.g. accounts rather than account.

A resource identifier is the unique value or key that is used to identify a resource.

Business domain resources are manipulated using HTTP methods as required by the business and resources should be addressable via a URI that is compatible with RFC1035.

The following is an example of a set of CRUD endpoints against an accounts resource with an identifier of {accountId}:

POST     /accounts                  < - - create a single account
GET      /accounts                  < - - return a list of accounts
GET      /accounts/{accountId}      < - - return a single account
PUT      /accounts/{accountId}      < - - update a single account
DELETE   /accounts/{accountId}      < - - delete a single account

The remainder of this section describes paths, resources, resource identifiers and the rules associated with a resource’s Create, Update, Read, Delete (CRUD) lifecycle model.

Paths

REST APIs use paths to access resources. The following shows a typical path with the OAS2 and OAS3 keywords used to define the path:

GET        https://apisandbox.finastra.com/finastraapis/v1/currencies
operation-\scheme/\----------host---------/\---basepath---/\--path--/     # at OAS2

GET        https://apisandbox.finastra.com/finastraapis/v1/currencies
operation-\------------------servers url------------------/\--path--/     # at OAS3

The following standards apply to paths:

Resources

This section provides guidelines on defining resources and identifiers.

Be Consistent

Resource names MUST be defined consistently both within an API for each GET, POST, PUT, DELETE method and across APIs.

When defining APIs and paths, it is recommended that the name of the API is the same as the principal resource within the API, for example, an account API should be named Accounts and have at least one endpoint using a /accounts resource.

API designers SHOULD avoid prefixing the /accounts resource in the Accounts API with parent resources e.g. avoid /customer/{customerId}/accounts unless necessary

Prefer Single Root Resource

In most scenarios the following paths which use a resource at root level can be used. This approach is used when the resource is not a sub-resource and the identifier is unique for all instances of the resource:

• POST /resources
• GET /resources
• GET /resources/{resourceId}
• PUT /resources/{resourceId}
• DELETE /resources/{resourceId}

The following rule applies:

Defining Sub-Resources

There are scenarios where multiple path segments and sub-resources can be used.

Sub-resources can be used when they are related to and dependant on the associated parent resource, for example: GET /clients/{clientId}/ratings/{ratingId} is used rather than GET /ratings/{ratingId} when a rating cannot be created in isolation.

If the rating resource is not dependant on the client resource then GET /ratings/{ratingId} should be used.

The following rule apply:

Defining Resources with Non-Unique Identifiers

When a resource identifier is NOT unique across all instances of a resource then there are the following options for defining the path:

Sub-resources can be used, for example, the following path handles scenarios where the accountId is not unique across all accounts, but is unique for a given clientId:

• GET /clients/{clientId}/accounts/{accountId}

Note that GET accounts/{accountId} would not support the same scenario because accountId is not unique across all accounts.

The following rules apply:

 Compound keys can be used when more than four path segments would be needed, for example, use:

• GET /resources/{resourceId} rather than
• GET /resource1s/{1id}/resource2s/{2id}/resource3s/{3id}

The following rules apply:

Defining Resource Actions

Use cases may arise where the HTTP method is not adequate to perform an action on a resource.

In these cases an action, named a resource controller, may be used against a resource, for example:

• POST /accounts/{accountId}/transactions/{transId}/confirm can be used to confirm an existing transaction

The resource controller approach is not recommended because alternative designs can often be found, for example, the same result can be achieved with: PATCH /accounts/{accountId}/transactions/{transId} with a payload of {"confirmation-status" : "complete" }

Similarly, an action should not be used when the action itself creates a new resource. In these cases its is better to define the resource on the path, for example, consider the case where a client requests a deal pricing scenario to create a pricing session - to achieve this the following path options are possible, however, the resource controller approach shown in the second example is not recommended:

• 1 - POST /pricing-sessions { dealId="deal1" , scenario="123"} returns {"pricingSessionId"="abc"} - this resource oriented approach is recommended
• 2 - POST /deals/{deal1}/price {"scenarioId" = "123"} returns {"pricingSessionId"="abc"} - this approach should be avoided

Resource Identifiers

An identifier is the unique value or key that is used to identify a resource, for example:

GET /accounts/{accountId}
{ 
    accountId = "2c76539b-c793-41aa-8082-87621b4e574b"
}

The following rules apply to resource identifiers:

Standards for Paths and Resources

The following lists the standards for paths and resources: