Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate to mkdocs #94

Merged
merged 14 commits into from
May 27, 2024
Prev Previous commit
Next Next commit
update
  • Loading branch information
karl-johan-grahn committed May 27, 2024
commit 0c82e3c7104cd2290c4bb182625d79e777844ef0
7 changes: 3 additions & 4 deletions content/api/foundations.md
Original file line number Diff line number Diff line change
@@ -14,7 +14,7 @@ to specify when more data is available and how to retrieve it. See the
for the details of request and response headers, status codes, limits,
ordering, and iteration.

# Require Secure Connections
## Require Secure Connections

Require secure connections with TLS to access the API, without exception.
It’s not worth trying to figure out or explain when it is OK to use TLS
@@ -25,10 +25,10 @@ http or port 80 to avoid any insecure data exchange. In environments where this
is not possible, respond with `403 Forbidden`.

Redirects are discouraged since they allow sloppy/bad client behaviour without
providing any clear gain. Clients that rely on redirects double up on
providing any clear gain. Clients that rely on redirects double up on
server traffic and render TLS useless since sensitive data will already
have been exposed during the first call.

## Separate Concerns

Keep things simple while designing by separating the concerns between the
@@ -47,4 +47,3 @@ Include an `ETag` header in all responses, identifying the specific
version of the returned resource. This allows users to cache resources
and use requests with this value in the `If-None-Match` header to determine
if the cache should be updated.

2 changes: 1 addition & 1 deletion content/api/general-guidelines.md
Original file line number Diff line number Diff line change
@@ -32,4 +32,4 @@ We use the OpenAPI specification (aka Swagger spec) as standard for REST API def

We also call the OpenAPI API definition the "API Reference definition" (or "API definition"); it provides all information needed by an experienced API client developer to use this API.

The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).
The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).
7 changes: 3 additions & 4 deletions content/api/how-to-model-workflows-in-rest-apis.md
Original file line number Diff line number Diff line change
@@ -5,8 +5,8 @@ RESTful Web Services are awesome for performing basic CRUD operations on databas
There are three options:

1. Use an Attribute for the Workflow’s State
2. Use Hyperlinks for Workflow Transitions
3. Use a Subresource for Workflow Transitions
1. Use Hyperlinks for Workflow Transitions
1. Use a Subresource for Workflow Transitions

## So which one should I pick?

@@ -20,9 +20,8 @@ As always, it depends on the context, but here are some quick guidelines:
| Transition Links | There are limits to which states you can go to depending on the current state. |
| Transition Subresource | The workflow is configurable by users, so states and transitions among them are not fixed, but can be changed at runtime. |


## Reference

Read following for more details:

- https://www.kennethlange.com/how-to-model-workflows-in-rest-apis/
- [How to Model Workflows in REST APIs](https://www.kennethlange.com/how-to-model-workflows-in-rest-apis/)
63 changes: 32 additions & 31 deletions content/api/http.md
Original file line number Diff line number Diff line change
@@ -16,71 +16,71 @@ Note: GET requests on collection resources should provide a sufficient filter me

### POST

POST requests are idiomatically used to create single resources on a collection resource endpoint, but other semantics on
single resources endpoint are equally possible. The semantic for collection endpoints is best described as »please add the
enclosed representation to the collection resource identified by the URL«. The semantic for single resource endpoints is
POST requests are idiomatically used to create single resources on a collection resource endpoint, but other semantics on
single resources endpoint are equally possible. The semantic for collection endpoints is best described as »please add the
enclosed representation to the collection resource identified by the URL«. The semantic for single resource endpoints is
best described as »please execute the given well specified request on the collection resource identified by the URL«.

- POST request should only be applied to collection resources, and normally not on single resource, as this has an undefined
- POST request should only be applied to collection resources, and normally not on single resource, as this has an undefined
semantic
- on successful POST requests, the server will create one or multiple new resources and provide their URI/URLs in the
- on successful POST requests, the server will create one or multiple new resources and provide their URI/URLs in the
response
- successful POST requests will usually generate 200 (if resources have been updated), 201 (if resources have been created),
- successful POST requests will usually generate 200 (if resources have been updated), 201 (if resources have been created),
and 202 (if the request was accepted but has not been finished yet)

More generally: POST should be used for scenarios that cannot be covered by the other methods sufficiently. For instance,
GET with complex (e.g. SQL like structured) query that needs to be passed as request body payload because of the URL-length
More generally: POST should be used for scenarios that cannot be covered by the other methods sufficiently. For instance,
GET with complex (e.g. SQL like structured) query that needs to be passed as request body payload because of the URL-length
constraint. In such cases, make sure to document the fact that POST is used as a workaround.

Note: Resource IDs with respect to POST requests are created and maintained by server and returned with response payload.
Posting the same resource twice is by itself not required to be idempotent and may result in multiple resource instances.
Anyhow, if external URIs are present that can be used to identify duplicate requests, it is best practice to implement POST
Note: Resource IDs with respect to POST requests are created and maintained by server and returned with response payload.
Posting the same resource twice is by itself not required to be idempotent and may result in multiple resource instances.
Anyhow, if external URIs are present that can be used to identify duplicate requests, it is best practice to implement POST
in an idempotent way.

### PUT

PUT requests are used to update single resources or an entire collection resources. The semantic is best described as
PUT requests are used to update single resources or an entire collection resources. The semantic is best described as
»please put the enclosed representation at the resource mentioned by the URL«.

- PUT requests are usually applied to single resources, and not to collection resources, as this would imply replacing the
- PUT requests are usually applied to single resources, and not to collection resources, as this would imply replacing the
entire collection
- PUT requests are usually robust against non-existence of resources by implicitly creating before updating
- on successful PUT requests, the server will replace the entire resource addressed by the URL with the representation
- on successful PUT requests, the server will replace the entire resource addressed by the URL with the representation
passed in the payload
- successful PUT requests will usually generate 200 or 204 (if the resource was updated - with or without actual content
- successful PUT requests will usually generate 200 or 204 (if the resource was updated - with or without actual content
returned), and 201 (if the resource was created)

Note: Resource IDs with respect to PUT requests are maintained by the client and passed as a URL path segment. Putting the
same resource twice is required to be idempotent and to result in the same single resource instance. If PUT is applied for
Note: Resource IDs with respect to PUT requests are maintained by the client and passed as a URL path segment. Putting the
same resource twice is required to be idempotent and to result in the same single resource instance. If PUT is applied for
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
creating a resource, only URIs should be allowed as resource IDs. If URIs are not available POST should be preferred.

### PATCH

PATCH request are only used for partial update of single resources, i.e. where only a specific subset of resource fields
should be replaced. The semantic is best described as »please change the resource identified by the URL according to my
change request«. The semantic of the change request is not defined in the HTTP standard and must be described in the API
PATCH request are only used for partial update of single resources, i.e. where only a specific subset of resource fields
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
should be replaced. The semantic is best described as »please change the resource identified by the URL according to my
change request«. The semantic of the change request is not defined in the HTTP standard and must be described in the API
specification by using suitable media types.

- PATCH requests are usually applied to single resources, and not on collection resources, as this would imply patching on
- PATCH requests are usually applied to single resources, and not on collection resources, as this would imply patching on
the entire collection
- PATCH requests are usually not robust against non-existence of resource instances
- on successful PATCH requests, the server will update parts of the resource addressed by the URL as defined by the change
- on successful PATCH requests, the server will update parts of the resource addressed by the URL as defined by the change
request in the payload
- successful PATCH requests will usually generate 200 or 204 (if resources have been updated with or without updated content
- successful PATCH requests will usually generate 200 or 204 (if resources have been updated with or without updated content
returned)

Note: since implementing PATCH correctly is a bit tricky, we strongly suggest to choose one and only one of the following patterns per endpoint, unless forced by a backwards compatible change. In preference order:

1. use PUT with complete objects to update a resource as long as feasible (i.e. do not use PATCH at all).
1. use PATCH with partial objects to only update parts of a resource, when ever possible. (This is basically [JSON Merge Patch](https://tools.ietf.org/html/rfc7396),
1. use PATCH with partial objects to only update parts of a resource, when ever possible. (This is basically [JSON Merge Patch](https://tools.ietf.org/html/rfc7396),
a specialized media type `application/merge-patch+json` that is a partial resource representation.)
1. use PATCH with [JSON Patch](http://tools.ietf.org/html/rfc6902), a specialized media type `application/json-patch+json` that
1. use PATCH with [JSON Patch](http://tools.ietf.org/html/rfc6902), a specialized media type `application/json-patch+json` that
includes instructions on how to change the resource.
1. use POST (with a proper description of what is happening) instead of PATCH if the request does not modify the resource in
1. use POST (with a proper description of what is happening) instead of PATCH if the request does not modify the resource in
a way defined by the semantics of the media type.

In practice JSON Merge Patch quickly turns out to be too limited, especially when trying to update single objects in large
collections (as part of the resource). In this cases JSON Patch can shown its full power while still showing readable patch
In practice JSON Merge Patch quickly turns out to be too limited, especially when trying to update single objects in large
collections (as part of the resource). In this cases JSON Patch can shown its full power while still showing readable patch
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
requests ([see also](http://erosb.github.io/post/json-patch-vs-merge-patch)).

### DELETE
@@ -107,14 +107,15 @@ Note: OPTIONS is rarely implemented, though it could be used to self-describe th

## Must: Fulfill Safeness and Idempotency Properties

An operation can be...
An operation can be:

- idempotent, i.e. operation will produce the same results if executed once or multiple times (note: this does not necessarily mean returning the same status code)
- safe, i.e. must not have side effects such as state changes

Method implementations must fulfill the following basic properties:

| HTTP method | safe | idempotent |
```txt
| HTTP method | safe | idempotent |
| ------------- | ------------- | ------------- |
| OPTIONS | YES | YES |
| HEAD | YES | YES |
@@ -123,4 +124,4 @@ Method implementations must fulfill the following basic properties:
| POST | NO | NO |
| DELETE | NO | YES |
| PATCH | NO | NO |

```
36 changes: 18 additions & 18 deletions content/api/json-guidelines.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
# JSON Guidelines

These guidelines provides recommendations for defining JSON data. JSON here refers to [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt) (which updates [RFC 4627](https://www.ietf.org/rfc/rfc4627.txt)),
the `application/json` media type and custom JSON media types defined for APIs. The guidelines clarifies some specific
These guidelines provides recommendations for defining JSON data. JSON here refers to [RFC 7159](http://www.rfc-editor.org/rfc/rfc7159.txt) (which updates [RFC 4627](https://www.ietf.org/rfc/rfc4627.txt)),
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
the `application/json` media type and custom JSON media types defined for APIs. The guidelines clarifies some specific
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
cases to allow JSON data to have an idiomatic form across teams and services.

## Must: Use Consistent Property Names

## Must: Property names must be snake_case (and never camelCase).
## Must: Property names must be snake_case (and never camelCase)
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved

No established industry standard exists, but many popular Internet companies prefer snake_case: e.g. GitHub, Stack Exchange,
Twitter. Others, like Google and Amazon, use both - but not only camelCase. It’s essential to establish a consistent look and
No established industry standard exists, but many popular Internet companies prefer snake_case: e.g. GitHub, Stack Exchange,
Twitter. Others, like Google and Amazon, use both - but not only camelCase. It’s essential to establish a consistent look and
feel such that JSON looks as if it came from the same hand.

## Must: Property names must be an ASCII subset

Property names are restricted to ASCII encoded strings. The first character must be a letter, an underscore or a dollar sign,
Property names are restricted to ASCII encoded strings. The first character must be a letter, an underscore or a dollar sign,
and subsequent characters can be a letter, an underscore, a dollar sign, or a number.

## Must: Use Consistent Property Values

## Must: Boolean property values must not be null

Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed
enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean
with enumeration of named values or statuses - for example accepted_terms_and_conditions with true or false can be replaced
Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean
with enumeration of named values or statuses - for example accepted_terms_and_conditions with true or false can be replaced
with terms_and_conditions with values yes, no and unknown.

## Must: Date property values should conform to RFC 3399
@@ -33,21 +33,21 @@ Use the date and time formats defined by [RFC 3339](http://tools.ietf.org/html/r
- for "date" use strings matching `date-fullyear "-" date-month "-" date-mday`, for example: `2015-05-28`
- for "date-time" use strings matching `full-date "T" full-time`, for example `2015-05-28T14:07:17Z`

Note that the [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types) format
"date-time" corresponds to "date-time" in the RFC) and `2015-05-28` for a date (note that the OpenAPI format "date" corresponds
Note that the [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types) format
"date-time" corresponds to "date-time" in the RFC) and `2015-05-28` for a date (note that the OpenAPI format "date" corresponds
to "full-date" in the RFC). Both are specific profiles, a subset of the international standard [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601).

A zone offset may be used (both, in request and responses) -- this is simply defined by the standards. However, we encourage
restricting dates to UTC and without offsets. For example `2015-05-28T14:07:17Z` rather than `2015-05-28T14:07:17+00:00`. From
experience we have learned that zone offsets are not easy to understand and often not correctly handled. Note also that zone
offsets are different from local times that might be including daylight saving time. Localization of dates should be done by
A zone offset may be used (both, in request and responses) -- this is simply defined by the standards. However, we encourage
restricting dates to UTC and without offsets. For example `2015-05-28T14:07:17Z` rather than `2015-05-28T14:07:17+00:00`. From
karl-johan-grahn marked this conversation as resolved.
Show resolved Hide resolved
experience we have learned that zone offsets are not easy to understand and often not correctly handled. Note also that zone
offsets are different from local times that might be including daylight saving time. Localization of dates should be done by
the services that provide user interfaces, if required.

When it comes to storage, all dates should be consistently stored in UTC without a zone offset. Localization should be done
When it comes to storage, all dates should be consistently stored in UTC without a zone offset. Localization should be done
locally by the services that provide user interfaces, if required.

Sometimes it can seem data is naturally represented using numerical timestamps, but this can introduce interpretation issues
with precision - for example whether to represent a timestamp as 1460062925, 1460062925000 or 1460062925.000. Date strings,
Sometimes it can seem data is naturally represented using numerical timestamps, but this can introduce interpretation issues
with precision - for example whether to represent a timestamp as 1460062925, 1460062925000 or 1460062925.000. Date strings,
though more verbose and requiring more effort to parse, avoid this ambiguity.

## Must: Standards must be used for Language, Country and Currency
Loading
Loading