Skip to content

Instantly share code, notes, and snippets.

@mikekistler

mikekistler/rest-api.md

Created October 16, 2022 15:43
Show Gist options
  • Save mikekistler/c35c211a88fa15ebbed33822fa3bf2b5 to your computer and use it in GitHub Desktop.
Save mikekistler/c35c211a88fa15ebbed33822fa3bf2b5 to your computer and use it in GitHub Desktop.
Download ZIP
Standard convetions / idioms for a REST API
Raw
rest-api.md

There are conventions in REST APIs that help users(developers) quickly understand how the resource works. This is the fundamental concept of REST.

Start with the resources

A REST API provides operations on resources and resource collections.

It should be readily apparent from just looking the paths in the REST API what the resources are.

Resources are generally (but not always) contained in resource collection, and resource collections are identified by static path segments that are followed by a path variable. The path variable is the "identifier" of a resource within the resource collection.

The resource collection name (the static path segement) should be a plural noun and the singular form of that noun is the type of resources in the collection.

Each resource should have a standard set of operations

There is a standard set of operations defined in REST - Create, Read, Update, Delete, and List, often referred to as "CRUDL" operations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment