Scribd
Upload
33 views

API Rest Conventions

The document outlines conventions for developing REST APIs at MasStack. It defines conventions for documentation, API paths, authentication, HTTP response codes, versioning, request and response bodies, and error responses. Next steps include defining additional best practices, standards, common models, authorization, parsing OpenAPI errors, an error dictionary, and pagination.

Uploaded by

paco38166
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
33 views

API Rest Conventions

The document outlines conventions for developing REST APIs at MasStack. It defines conventions for documentation, API paths, authentication, HTTP response codes, versioning, request and response bodies, and error responses. Next steps include defining additional best practices, standards, common models, authorization, parsing OpenAPI errors, an error dictionary, and pagination.

Uploaded by

paco38166
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 10

Api Rest Conventions

MasStack
Index
Main points to be defined

Defined
- Documentation in Dev Portal
- API Path conventions
- Basics of AuthN and AuthZ
- Recommended HTTP Codes
- Versioning Strategy
- Request and Response body conventions
- Error body definition

Next Steps
- Best practices II
- Standards (date, language, country, currency, etc)
- Common models - Ubiquitous language
- AuthZ - Permissions and roles
- Parse open api lib errors
- Error dictionary
- Pagination

2
Documentation
https://mas.fyi/documenting-best-practices

Developer Portal
Documenting best practices developers.masstack.com

3
Paths
API Gateway

api.masstack.com/vX/orgs/{org_id}/request_path

Naming

- English
- `snake_case`

4
AuthN & AuthZ
Request AuthN/AuthZ, Business & Application AuthnN

5
HTTP Codes
Recommended HTTP Codes

Success Redirect Error Internal Error

200 - GET resource success 308 - In deprecated API, 400 - POST, PUT & PATCH 500 - Internal server Error
200 - GET resource list success redirection to release note invalid body 501 - Not implemented (e.g.
200 - GET empty resource list 400 - GET query param invalid Method not developed)
success 401 - Unauthorized 502 - Bad gateway
201 - POST success 404 - GET item not found 503 - Service unavailable (e.g.
204 - PUT, POST, DELETE & 429 - Too Many requests maintaining, overload…)
PATCH success with empty 504 - Timeout
response
206 - GET resource list with
pagination*

2xx 3xx 4xx 5xx

6 * Should be detailed in next iteration. See “Next Steps” slide


Versioning
API Versioning conventions

This refers to the version number found in the URL path of any API request, for example:
catalogue.masstack.com/v2/orgs/{org_id}/commercial_profiles. This style of versioning is known as URI versioning.

- Versions are only represented by a major figure, not by minor or patch.


- Deprecations for current versions whenever a new version is announced is 6 months.
- After 6 months, the deprecated version will no longer be supported but will remain accessible for at least 1 year.
- Our APIs will allow requests only from two versions simultaneously, however we won't support the older of the two.

Changes which must involve new API version Changes shouldn’t involve new API version

- Addition of a new required parameter - Added new resources


- Removal of an existing endpoint - Added data in the response
- Removal of any field in the response (either required or optional) - Changed technologies (Java to Ruby)
- Removal of a query parameter - Changed your application’s services
- Restructuring of the input or output format - Changing text in error messages
- Changing the name or data type of an existing input parameter or - Availability of new scopes
output value - Adding an extensible ENUM* value
- Changing the name of a field
- Changing the resource name
- Changing a response code
- Changing error types
- Changes to existing authorization scopes
- Change in behavior of endpoints (e.g., async vs sync stats)
- Adding a non-extensible ENUM* value

7 * For more details, see “Response/Request Body > Enum” slide


Response / Request body
Fields naming and values conventions

Naming Enums Extensible Enums

- English - English - English


- `snake_case` - Uppercase - Uppercase
- Ubiquitous language* - Strings, not numeric - Strings, not numeric
- Common models* - If new value added, new - If new value added, new
mayor version is needed mayor version is needed

Examples OK Examples OK Examples OK


- subscription_id - subscription_status: - subscription_type:
- account_id [ACTIVATED, IN_PROGRESS] [MOBILE, SECURITY, TV]

Examples KO Examples KO Examples KO


- bonusId (must be snake_case) - proffesion_id: [1, 2, 3] - sub_status: [ACTIVATED,
- producto_id (must be english) (mustn’t be numeric) CLOSED] (isn’t extensible; adding
- sub_status: [ACTIVADO] a new value implies a change in the
(must be in english) logic)

8 * Should be detailed in next iteration. See “Next Steps” slide


Error body
4xx and 5xx response body conventions

‘errors’: [
{
‘code’: ‘XXX_21201’,
‘title’: ‘TITLE_OF_THE_DOMAIN_ERROR’,
‘ref’: "https://developers.masstack.com/en/docs/apis_domain_doc_swagger/2/apioverview/#error’
‘details’: ‘message & details of the error’
}
]

- There should at least be one item in `errors` array


- Code and title must belong to a domain dictionary
- Code prefix should be the key of the domain
- `ref` should be a location in developer portal
- Error object model will be created in `commons` package in `mm-monorepo`
- A library to manage error dictionary and response will be implemented in `commons` package in `mm-monorepo`

9
Next Steps
Next points to be defined

- Best practices II. Posible inspiration → https://mas.fyi/api-rest-best-practices and


https://mas.fyi/event-drive-api-best-practices
- Standards (date, language, country, currency, etc)
- Common models - Ubiquitous language
- AuthZ - Permissions and roles
- Parse OpenApi lib errors
- Error dictionary
- Pagination (206 and array response)

10

You might also like