Conventions =========== The guidelines and conventions follow the Open Stack Foundation specifications - https://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html 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 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/...) Formatting ---------- - All objects should be represented in JSON format. - JSON documents should be encoded in UTF-8 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)" 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. 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") Percentage ---------- - Percentage shall be represented as a floating point number - The range shall be [0.0, 1.0] 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 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 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 | | | | | | - for example, a required parameter is missing | +-------------+-------------------------------------------------------------------------------------------------------+ | 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 | | | | | | - for example, a query parameter is expecting a date, but the value doesn't follow the date format | +-------------+-------------------------------------------------------------------------------------------------------+ | 500 | Internal Server Error | +-------------+-------------------------------------------------------------------------------------------------------+