TheCloneArmy/RestApiGuide
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Refining usage of notice shortcodes

Browse Source
This commit is contained in:
Todd Fredrich
2023-01-20 19:13:04 -07:00
parent ee3f29da12
commit 2a36363604
5 changed files with 14 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
content/basics/restquicktips.md
View File

@ -6,7 +6,7 @@ weight: 20
Whether it's technically RESTful or not (according to the six constraints mentioned previously), here are a few recommended REST-like concepts. These six quick tips will result in better, more usable services.
## Use HTTP Methods to Make Requests Mean Something
{{% notice tip "Verb-Free URLs" "exclamation-circle" %}}
{{% notice tip "Verb-Free URLs" %}}
API consumers are capable of sending GET, POST, PUT, PATCH and DELETE methods (or verbs), which greatly enhance the clarity of a given request.
Therefore, it is recommended that no verbs (action words) appear in the URL. Instead leverage the HTTP Methods to provide the verb.
@ -22,12 +22,12 @@ Generally, the five primary HTTP methods are used as follows:
| DELETE | Remove/delete a specific resource by an identifier. |
| POST | Create a new resource. Also a catch-all verb for operations that don't fit into the other categories. |
{{% notice warning "Safety" "exclamation-circle" %}}
{{% notice warning "Safety" %}}
GET requests MUST not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource identified by the URI MUST not change.
{{% /notice %}}
## Provide Sensible Resource Names
{{% notice tip "Verb-Free URLs" "exclamation-circle" %}}
{{% notice tip "Verb-Free URLs" %}}
Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does. As humans are involved in understanding an API, this clarity counts.
{{% /notice %}}