diff --git a/_config.yml b/_config.yml index 2351f48..69ff5ee 100644 --- a/_config.yml +++ b/_config.yml @@ -48,7 +48,7 @@ exclude: host: 0.0.0.0 port: 9876 -latest_version: 1.0 +latest_version: 2.0 navigation: - title: Current Version diff --git a/versions/1.0/index.md b/versions/2.0/index.md similarity index 87% rename from versions/1.0/index.md rename to versions/2.0/index.md index 0023127..19ba97e 100755 --- a/versions/1.0/index.md +++ b/versions/2.0/index.md @@ -1,7 +1,7 @@ --- layout: default -title: "Version - 1.0" -version: 1.0 +title: "Version - 2.0" +version: 2.0 --- # Introduction @@ -31,11 +31,13 @@ Anywhere a **URI** is specified, it must adhere to the following rules: * **MUST** be relative path as it's sometimes difficult for servers to construct an absolute path reliably. * **MUST** use `-` or hyphen as delimiter for words within the path. * **MUST** use `snake_case` for query string parameters. -* **SHOULD** use lowercase characters for words within the path basename (up to the last occurrence of '/'). This is to account for various-case `id`s, such as those found in URL shorteners. E.g. `https://goo.gl/VwUrzz` +* **MUST NOT** have file extensions. +* **SHOULD** use lowercase characters for [resource paths](#conventions-resource-paths) such as collection or singletons. Exceptions can be made for singleton resources that are unique. + * `https://api.company.com/security/v1/policies/VwUrzz` ### Sub-service Path -APIs **MUST** provide a sub-service path in the URI as a way to create a namespace for your endpoints. +APIs **MUST** provide a sub-service path in the [URI](#conventions-uri) as a way to create a namespace for your endpoints. A `sub-service` URI path **MUST** have the following: @@ -44,9 +46,73 @@ A `sub-service` URI path **MUST** have the following: These two rules promote clear differentiation of sub-services and versions, allowing independent development. +### Versioning + +APIs **MUST** provide versioning in the URI path, following the sub-service path. + +**MUST** increase either `Major` or `Minor` in the version path whenever a breaking change is introduced. `/vMajor[.Minor]` + +* **SHOULD NOT** increase version if adding new endpoints or fields. + +* **SHOULD** increase version if changing behavior for an existing API endpoint: + + * Such as modifying the HTTP status code + * Changing data format + * Changing the resource, ie. removing or renaming fields + * Anything that would violate the [Principal of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) + +``` +https://api.company.com/sub-service/v1 +https://api.company.com/sub-service/v1.1 +``` + +### Resource Paths + +A resource path represents data a client can consume and interact with. + +Resource paths must adhere to the following rules: + +* **MUST** be named a noun. +* **MAY** have sub-collections, however API developers must avoid deeply nesting resources. +* **MUST** represent a valid resource. +* **MUST NOT** be used for filtering or anchoring. +* **MUST** use plural form for collections. +* **MUST** singular form for singletons. + + +An example of a `collection` type resource are the following: +``` +https://api.company.com/security/v1/configs +https://api.company.com/security/v1/policies +``` + +An example of a `singleton` type resource are the following: +``` +https://api.company.com/security/v1/global-policy +https://api.company.com/security/v1/policies/VwUrzz +https://api.company.com/iam/v1/users/a683057f-0eef-49bd-801e-5958cdbabd50 +``` + +### Pagination + +An API **MAY** provide pagination on collection [resources](#conventions-resource-paths). + +APIs **MUST** use the following query parameters for pagination and sorting: + +* `limit`: The number of items to return within the collection. +* `offset`: The offset from which to start pagination. + +APIs **SHOULD** set the default size of a collection to `25` items. + +An example of pagination query parameters: +``` +https://api.company.com/security/v1/configs?offset=5&limit=100 +https://api.company.com/security/v1/policies?offset=25&limit=25 +``` + ### HTTP Status Codes -APIs **MUST** respond to requests with an Http Status Code that is found in the following list: +APIs **MUST** respond to requests with an HTTP Status Code that is found in the following list: status code | description | [error code](#document-components-error-codes) | notes --- | --- | --- | --- @@ -63,7 +129,7 @@ status code | description | [error code](#document-components-error-codes) | not 401 | Unauthorized | unauthorized | The request did not include a required authentication component 403 | Forbidden | forbidden | The request has failed authorization checks 404 | Not found | not_found | Resource not found -405 | Method not allowed | method_not_allowed | The http method was not valid at the specified URI +405 | Method not allowed | method_not_allowed | The HTTP method was not valid at the specified URI 409 | Conflict | invalid_operation | The request could not be completed due to a conflict with the current state of the target resource 413 | Payload Too Large | payload_too_large | Request payload is too large and the server will not process it 422 | Unprocessable Entity | The request and it's body are valid and parseable, but are malformed in a semantic way (missing data, incorrect structure) @@ -74,34 +140,14 @@ status code | description | [error code](#document-components-error-codes) | not 504 | Gateway timeout | gateway_timeout | The gateway server or proxy failed to receive a response from upstream server while fulfilling a request -### Versioning - -APIs **MUST** provide versioning in the URI path, following the sub-service path. - -**MUST** increase either `Major` or `Minor` in the version path whenever a breaking change is introduced. `/vMajor[.Minor]` - -* **SHOULD NOT** increase version if adding new endpoints or fields. - -* **SHOULD** increase version if changing behavior for an existing API endpoint: - - * Such as modifying the HTTP status code - * Changing data format - * Changing the resource, ie. removing or renaming fields - * Anything that would violate the [Principal of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) - - -`https://api.company.com/sub-service/v1` - -`https://api.company.com/sub-service/v1.1` - -## Naming Conventions +### Naming Conventions * **MUST** use `PascalCase` and be singular to represent a `@type`. * **MUST** use `snake_case` to represent a property. * **MUST NOT** use `@` keyword for custom properties as it is reserved. -## Date Handling +### Date Handling All dates **MUST** be represented as string values following the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard. @@ -136,7 +182,7 @@ An example of UTC _datetime_ value. } ``` -## Time Series +### Time Series APIs that need to implement time series functionality **MUST** refer to specifications defined in the [time series]({{site.url}}/versions/{{site.latest_version}}/time-series) section. @@ -349,20 +395,20 @@ A `Collection` **MAY** have the following: ```json { - "@id": "/users?page=2&page_size=4", + "@id": "/users?offset=5&limit=4", "@type": "Collection", "@links": { "first": { - "href": "/users?page=1&page_size=4" + "href": "/users?offset=0&limit=4" }, "next": { - "href": "/users?page=3&page_size=4" + "href": "/users?offset=10&limit=4" }, "previous": { - "href": "/users?page=1&page_size=4" + "href": "/users?offset=0&limit=4" }, "last": { - "href": "/users?page=5&page_size=4" + "href": "/users?offset=14&limit=4" } }, "items": [ @@ -391,17 +437,17 @@ An example of a `collection` where the `items` are _not Hyperion_ : "@id": "/users?page=2&page_size=4", "@type": "Collection", "@links": { - "first": { - "href": "/users?page=1&page_size=4" + "first": { + "href": "/users?offset=0&limit=4" }, "next": { - "href": "/users?page=3&page_size=4" + "href": "/users?offset=10&limit=4" }, "previous": { - "href": "/users?page=1&page_size=4" + "href": "/users?offset=0&limit=4" }, "last": { - "href": "/users?page=5&page_size=4" + "href": "/users?offset=14&limit=4" } }, "items": [ diff --git a/versions/1.0/time-series/index.md b/versions/2.0/time-series/index.md similarity index 99% rename from versions/1.0/time-series/index.md rename to versions/2.0/time-series/index.md index d1086c6..616c2c5 100644 --- a/versions/1.0/time-series/index.md +++ b/versions/2.0/time-series/index.md @@ -1,7 +1,6 @@ --- layout: default title: "Time Series" -version: 1.0 --- # Time Series Introduction