API Designer Check-List

The purpose of this checklist is to collect all best practices for REST Design, and organize them into an easy to use checklist.

1 Identify functionalities from business requirements.

Use this API-Template.v1.yaml in order to get a starting point and understand how to apply the Best Practices into the Swagger
Contract Design.
2 Identify resources.
3 Identify actions.
4 Map actions to standard http verbs if possible.

Action Create Read, List, Find Update & Create if not exist Update only if exist Delete

HTTP verb POST GET PUT PATCH DELETE

HTTP verb in OpenBank - - POST collection/{resourceId}/update POST collection/{resourceId}/partial-update POST collection/{resourceId}/delete

Note:

If do you want update an resourceId and create it in case of this rosourceId don’t exist, you need to use the PUT (only when the API consumer is able to provide the resourceId and it isn’t auto generated by the backend).
If we want to update only one existing resourceId we need to the PATCH verb.

Also, take in mind that the PUT/PATCH & DELETE are not allowed in Openbank, but we have the /update, /partial-update and /delete workarounds.

5 Check if the resource is available in the API Catalog.

6 If is a new resource identify all the attributes.
7 If is an existing resource add the new attributes in all API methods where resource is used.
8 The same business concept should be used across the API Catalog with same structure, attributes and types. Data Dictionary
should be used to check existing attributes and objects.
9 If the new methods are going to be added to an existing API Designer should review the existing API to append new functionalities
consistently.
10Assure than every time than the resource is requested or retrieved in the API is with the same structure and attributes. (Self-
generated fields only applies to response). We can call this the detail view of a resource.
Only exception for this is when retrieving a collection of resources (we can call this the list view of resource). In this case is possible
to retrieve a small set of the resource properties but never more than the detailed view.
Please check: REST Design magic formula

11When creating or updating a resource, the fields part of the request who belongs to the resource should be retrieved in the
response.
Please check: REST Design magic formula

12Use always plural in urls to refer to the resource collection.

13Use always verbs to refer to actions in urls if none of standard http verbs can satisfy the purpose.
14Never user upper case in urls.
15Use spin-case naming in urls.
16Use camelCase naming for attributes in request/responses and definitions (Models)
17Use human readable naming in attributes. Never use technical namings.
18Avoid use acronyms or abbreviations in attributes.
19Use the appropriate type for every attribute.
20Use API Portal Data Dictionary to check if the attribute is already being used to just reuse the structure.
21For Dates use "Date" as Suffix.
22For Amount Use "Amount" as Suffix.
23For Boolean Use "is" as Prefix.
24Use prefix “from” for greater than.
25Use prefix “to” for lower than.
26Use 200 status code for successful executions and 201 status code when creating a resource.
27 Each end point need to have defined the below error codes (supported on T24 IRIS)
CONDITIONAL: If the endpoint + method want to retrieve (aka GET), Erase (aka DELETE) or Partial Update (aka PATCH) a collections/{resourceId}, the 404 and 409 Error Codes need to be added.
Note: The main collections (without resourceId) never could be have a 404 error codes, in case to have an empty collection, the response code need to be 204 - No content.
Please see the HTTP Status Code's Standards in order to understand what error types is required & allowed in each operation type.

Mandatory Response Codes Matrix

Method / Endpoint Type Collections Resources Controllers

/resources /resources/{resourceId} /resources/{resourceId}/controller

GET
200 200
204 400
400 401
401 403
403 404
500 500
503 503
504 504

POST Not recommended to use it to create a resource.

201 200
400 201 204
401 400 400
403 401 401
500 403 403
503 409 404
504 500 500
503 503
504 504

POST ( for PUT - complete update) /resources/{resourceId}/update

201
(If the resourceId don'it exist, then create it.
If the API cant create a resource use PATCH not PUT)
204
400
401
403
500
503
504

POST ( for DELETE) /resources/{resourceId}/delete

200
204
400
401
403
404
409
500
503
504

POST ( for PATCH - Partial update) /resources/{resourceId}/partial-update

204
400
401
403
404
500
503
504

Response Code Required Description

400 - Bad Request MANDATORY Used to indicate nonspecific failure 400 is the generic client side error status, used when no other 4xx error code is appropriate.

401 - Unauthorized MANDATORY Must be used when there is a problem with the client’s credentials.

403 - Forbidden MANDATORY Should be used to forbid access regardless of authorization state.

404 - Not Found CONDITIONAL Must be used when a client’s URI cannot be mapped to a resource

409 - Conflict CONDITIONAL Indicates that the request could not be completed due to a conflict with the current state of the target resource.

500 - Internal Server Error MANDATORY Should be used to indicate API malfunction

503 - Service Unavailable MANDATORY Indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

504 - Gateway timeout MANDATORY Indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.

28Use country as optional Header. (Not applies for T24 apis.)

29Mandatory definition Headers:
Each end-point & method must to have defined the below 3 headers parameters (in this order -
accessToken, openBankCorrelationId, progressId).
Notes:

1. For existing signed off API, this headers need to be added in the next Swagger Contract change.
2. For the API where we are working now (in the flight), this headers need to be added now.
3. Each API stream need add this task in your backlog, this guideline rule will be applied from now).

Example:

Security Headers

- name: accessToken
in: header
description: Login Token
required: true
type: string
- name: openBankCorrelationId
in: header
description: Correlation Identifier
required: false
type: string
- name: progressId
in: header
description: Progress Identifier
required: false
type: string

30Validate the design with Functional Authority.

31Everytime that we use amounts we should retrieve a currency.
32
Complete the IRD/ASD using the provided ASD TEMPLATE and sent to review:
Functional SME review mandatory.
Architect review if is a complex solution like cards.
API Governance mandatory.
If all agree go and review with Customer.
33
Complete the swagger based on IRD/ASD using the tools or https://editor.swagger.io
34
Include examples in the swagger for every request/response
35
Example values should follow the examples best practices:
Good names for persons.
Real addresses for countries.
Good status, types, enums, codes etc.
Valid amounts.
Samples that matches a business case.
Good dates.
Good currencies.
Informing the mandatory fields.
Following the data type schema.

36
Validate examples with Functional Authority or request him to provide values to generate the samples.
37
Versioning. See API Versioning strategy.

For new apis the value of version section of swagger will be 1.0.0.
Basepath section of swagger will contain the Major portion of the version value.

38API Title and description should be informed with enough quality in the descriptions.
39Use tags to group operations of a resource.
401 - Put summary in all operations.
2 - Put descriptions in all operations and attributes.
path (endpoints) descriptions
input parameters / fields in the schema need to have descriptions
responses descriptions
output fields in the schema need to have a description

41Execute API Linter. http://100.64.12.179:8085/

42Execute API Diff if we are including a new feature in an existing API. This will inform us about the compatibility of the new change.
42Create the Pull Request following the Swagger baseline strategy to get API Governance review.
43Share bitbucket link of approved Swagger with Customer after the sign-off.
44The input parameters order should be
1. Headers
2. Path
3. Query Parameters (if exist, i.e.: in pagination)
4. Body

45Ensure that all the endpoints with POST method , send all the fields that are there in the request also in the response.
46 Only https scheme is allowed (http without security is forbidden)

47 Use the common error codes Models

In order to re-define every time the error codes Models and prevent to have different error code Models, use the bellow Models by default.

errorObject:
type: object
description: Error details
properties:
code:
type: string
description: Error code
example: '400'
description:
type: string
description: Error description
example: Bad Request
level:
type: string
description: Error level
enum: [INFO, ERROR, WARNING, FATAL]
example: ERROR
message:
type: string
description: Error message (detailed description)
example: Invalid Request. Please, check the data in the request (QueryString Parameters and/or Body).
title: errorObject
example:
code: '400'
description: Bad Request
level: ERROR
message: Invalid Request. Please, check the data in the request (QueryString Parameters and/or Body).

400BadRequestError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 400BadRequestError
example:
errors:
- code: '400'
description: Bad Request
level: ERROR
message: Invalid Request. Please, check the data in the request (QueryString Parameters and/or Body).
 401UnauthorizedError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 401UnauthorizedError
example:
errors:
- code: '401'
description: Unauthorized Error
level: ERROR
message: Unauthorized Error. The API client is not allowed to consume this resource. Check the user
credentials.

403ForbiddenError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 403ForbiddenError
example:
errors:
- code: '403'
description: Forbidden Error
level: ERROR
message: Forbidden Error. The user is not allowed to executed this operation.

404NotFoundError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 404NotFoundError
example:
errors:
- code: '404'
description: Resouce not found
level: ERROR
message: Resouce not found. Please, check the ResourceId specified.

409ConflictError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 409ConflictError
example:
errors:
- code: '409'
description: Conflict
level: ERROR
message: Conflict with the current state of the target resource.

500InternalServerError:
type: object
 description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 500InternalServerError
example:
errors:
- code: '500'
description: Internal Server Error
level: ERROR
message: Internal Server Error. The server encountered an unexpected condition that prevented it from
fulfilling the request.

503ServiceUnavailableError:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 503ServiceUnavailableError
example:
errors:
- code: '503'
description: Service Unavailable Error
level: ERROR
message: Service Unavailable Error. The server is temporarily unable to handle a request.

504GatewayTimeOut:
type: object
description: List of errors
properties:
errors:
type: array
description: Details of each of the errors
items:
$ref: '#/definitions/errorObject'
title: 504GatewayTimeout
example:
errors:
- code: '504'
description: Gateway Time Out
level: ERROR
message: Gateway Time Out. The server did not receive a timely response.

48 Ensure that the Swagger Editor https://editor.swagger.io don´t show errors or warnings.

example of warnings:
49 Arrays & Pagination

A. If do you need response or request more than one resource (array), we need add the “data” structure like you see in this example:

Use data structure to enclose arrays

{
"data":[
{
"Object 1":"value"
},
{
"Object 2":"value"
},
{
"Object N":"value"
}
]
}

B. If do you need response more than one resource (array and the result need to be paginated, we need add the “data” and HATEOAS ( “links”) structure like you see in this example:
Click on this HATEOAS link to see all the implementation details

Use data and links for pagination

{
"data":[
{
"Object 1":"value"
},
{
"Object 2":"value"
},
{
"Object N":"value"
}
],
"links":{
"prev":{
"href":"string"
},
"next":{
"href":"string"
},
"first":{
"href":"string"
}
}
}