2.2. Conventions
The guidelines and conventions follow the Open Stack Foundation specifications
2.2.1. Naming Conventions
- URI endpoints
- In a REST API, the endpoint should represent a resource being accessed using the noun of the resource.
For example: https://provider.com/specifications
A resource can be a singleton or a collection. Use “singular” name to denote a singleton and a “plural” name to denote a collection.
Resource names should use all lowercase characters
Use the hyphen (-) character to separate words when a resource name has more than one word
- Use the forward slash (/) character in the path portion of the URI to indicate a hierarchical relationship between resources
For example: https://provider.com/machine/name
Resource names should not include underscores or other punctuation (other than hyphen)
- Objects and fields
Object and field names should use the snake_case style
Object and field names should use all lowercase characters
2.2.2. Versioning
The API should use a URI versioning scheme where the first element of the path contains the target version identifier (e.g. https://{provider url}/v1/…)
2.2.3. Formatting
All objects should be represented in JSON format.
JSON documents should be encoded in UTF-8
2.2.4. Data Types
The possible JSON data types should comply to the definition provided by the JSON Schema Validation standard (https://json-schema.org/draft/2019-09/json-schema-validation.html):
A type “MUST be one of the six primitive types (“null”, “boolean”, “object”, “array”, “number”, or “string”), or “integer” which matches any number with a zero fractional part)”
2.2.5. Floating point representation
Floating point numbers shall use the decimal point notation with the ‘.’ character as the delimiter between integer and fractional part of a number.
2.2.6. Date and Time
Date and Time should use ISO 8601 format
Dates should use the calendar date format “YYYY-MM-DD”
Times should use the 24 hours clock format “hh:mm:ss” where hh has a value between 00 and 24 (where 24 is only used to denote midnight at the end of a calendar day)
Date-times should use the format “YYYY-MM-DDThh:mm:ss”
- Durations should be represented by the format “P[n]Y[n]M[n]DT[n]H[n]M[n]S”
Note that terms are optional. These examples are valid: “PT20S”, P1DT1M”, “PT36H”
- Time should be in Coordinated Universal Time (UTC)
Add a ‘Z’ directly after the time without a space (e.g. “14:30:00Z”)
2.2.7. Percentage
Percentage shall be represented as a floating point number
The range shall be [0.0, 1.0]
2.2.8. Geolocation
- Geolocation data should follow the ISO 6709 Standard representation of geographic point location by coordinates
Longitude and latitude should be represented as degrees
The longitude range should be [-180.0, 180.0]
The latitude range should be [-90.0, 90.0]
- At best, the accuracy is to the nearest cm and the unit is m.
For example, if the accuracy of a geolocation is 5cm, the accuracy is represented as 0.05
2.2.9. Images
Images shall be defined as a full URI to the file containing the image
The URI shall be public (such as a Content Delivery Network for example)
The images should have file sizes appropriate for web application
2.2.10. Status codes
Status codes are a subset of the HTTP status codes as defined in RFC 2616 and RFC 6585
Status Code |
Description |
|---|---|
200 |
A HTTP Get request is successful |
201 |
A HTTP POST is successful and the resource has been successfully created |
204 |
An endpoint is not implemented |
400 |
Bad Request - The request could not be understood by the server due to a malformed syntax
|
401 |
Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials |
403 |
The server understood the request but is refusing to fulfil it because of an issue with the value of a query parameter
|
500 |
Internal Server Error |