REST API Guidelines #541
Labels
No Label
backups
blog
bootstrapping
bug
changes-requested
cli
documentation
duplicate
enhancement
facts
help wanted
invalid
Inventory
low_prio
manager
modules
needs-review
networking
packaging
question
secrets
template
test
tooling
user-testing
vm
wontfix
No Milestone
No project
2 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: clan/clan-core#541
Loading…
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
API Guidelines
This issue serves to collect our common understanding how to design our API so that it is extensible and usable and understandable.
Resource oriented
A resource-oriented API is generally modeled as a resource hierarchy, where each node is either a simple resource or a collection resource. For convenience, they are often called a resource and a collection, respectively.
Examples of Resource Nouns:
machine
user
flake
Often resources have sub-resources. Even if it is not foreseen, it is recommended to use plural (trailing
s
) on resources to allow them to be collections of sub-resources.e.g,
users
->
users/*/profile
Verbs
Verbs should not be part of the URL
Bad:
/api/create-products
Good:
/api/products
Only resources are part of the URL, verbs are described via the HTTP Method.
Exception:
If a different HTTP Method must be used for technical reasons it is okay to terminate the path with a (short) verb / action.
Okay ish:
/api/products/create
Usually the following HTTP Methods exist to interact with a resource
Every resource should be CRUD compatible
All API resources MUST be designed in a way that allows the typical CRUD operations.
Where crud stands for:
C - Create
R - Read
U - Update
D - Delete
Resources should implement at least a "Read" operation.
Body
Use JSON as an exchange format.
All responses MUST be JSON parseable.
Bad:
bare string
Better:
"quoted string"
Best: (Enveloped see next section)
{ name: "quoted string"}
Errors should have a consistent JSON format, such that it is clear in which field to look at for displaying error messages.
Envelop all Data collections
Response data should be wrapped into an JSON Object
{}
Lists
[]
should also contain Objects{}
.This allows everything, to be extensible, without breaking backwards compatibility. (Adding fields is trivial, since the schema doesn't change)
Example:
Bad Example of a breaking change:
GET /api/flakes
old
new
Those kind of breaking changes can be avoided by using an object from the beginning.
Even if the object only contains one key, it is extensible, without breaking.
More will follow.
Opened a PR putting the guidelines in our docs: #595