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

2
content/basics/_index.md
View File

@ -10,7 +10,7 @@ weight = 5
# Learn REST API Basics # Learn REST API Basics
Quickly learn the basics of what REST is and the core concepts behind it. Quickly learn the basics of what REST is and the core concepts behind it.
{{% notice style="tip" title="Here's a Quick Tip!" icon="exclamation-circle" %}} {{% notice tip "Here's a Quick Tip!" %}}
Be on the lookout for Quick Tips in boxes like this throughout the course. They'll provide a jump-start to your super-powers Be on the lookout for Quick Tips in boxes like this throughout the course. They'll provide a jump-start to your super-powers
(or at least give you a leg up on getting your job done)! (or at least give you a leg up on getting your job done)!
{{% /notice %}} {{% /notice %}}

11
content/basics/httpmethods.md
View File

@ -5,6 +5,7 @@ weight: 30
--- ---
The HTTP verbs (or methods, as they are formally called) comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others. The HTTP verbs (or methods, as they are formally called) comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.
## Overview
Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs: Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:
| Method | CRUD | Entire Collection (e.g. /customers) | Specific Item (e.g. /customers/{id}) | | Method | CRUD | Entire Collection (e.g. /customers) | Specific Item (e.g. /customers/{id}) |
@ -16,7 +17,7 @@ Below is a table summarizing recommended return values of the primary HTTP metho
| DELETE | Delete | 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. | 200 (OK). 404 (Not Found), if ID not found or invalid. | | DELETE | Delete | 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. | 200 (OK). 404 (Not Found), if ID not found or invalid. |
Below is a more-detailed discussion of the main HTTP methods. Below is a more-detailed discussion of the main HTTP methods.
### POST ## POST
The POST verb is most-often utilized to *create* new a resource. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc. The POST verb is most-often utilized to *create* new a resource. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.
On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status. On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.
@ -27,7 +28,7 @@ __Examples:__
* POST http://www.example.com/customers * POST http://www.example.com/customers
* POST http://www.example.com/customers/12345/orders * POST http://www.example.com/customers/12345/orders
### GET ## GET
The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request. According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
@ -39,7 +40,7 @@ __Examples:__
* GET http://www.example.com/customers/12345/orders * GET http://www.example.com/customers/12345/orders
* GET http://www.example.com/buckets/sample * GET http://www.example.com/buckets/sample
### PUT ## PUT
PUT is most-often utilized for *update* capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. PUT is most-often utilized for *update* capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.
However, PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all. However, PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all.
@ -57,7 +58,7 @@ __Examples:__
* PUT http://www.example.com/customers/12345/orders/98765 * PUT http://www.example.com/customers/12345/orders/98765
* PUT http://www.example.com/buckets/secret_stuff * PUT http://www.example.com/buckets/secret_stuff
### PATCH ## PATCH
PATCH is used for *modify* capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource. PATCH is used for *modify* capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource, but in some kind of patch language like JSON Patch or XML Patch. This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource, but in some kind of patch language like JSON Patch or XML Patch.
@ -69,7 +70,7 @@ __Examples:__
* PATCH http://www.example.com/customers/12345/orders/98765 * PATCH http://www.example.com/customers/12345/orders/98765
* PATCH http://www.example.com/buckets/secret_stuff * PATCH http://www.example.com/buckets/secret_stuff
### DELETE ## DELETE
DELETE is pretty easy to understand. It is used to *delete* a resource identified by a URI. DELETE is pretty easy to understand. It is used to *delete* a resource identified by a URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses. On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.

4
content/basics/restcontstraints.md
View File

@ -50,4 +50,6 @@ Servers are able to temporarily extend or customize the functionality of a clien
Complying with these constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability. Complying with these constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.
NOTE: The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful. {{% notice info "RESTful or Not?" %}}
The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful.
{{% /notice %}}

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. 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 ## 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. 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. 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. | | 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. | | 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. 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 %}} {{% /notice %}}
## Provide Sensible Resource Names ## 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. 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 %}} {{% /notice %}}

2
content/basics/whatisrest.md
View File

@ -5,7 +5,7 @@ weight: 10
--- ---
The term RESTful APIs or RESTful services is a hot topic. So what is REST? And how do we create a so-called RESTful API? Good question! Let's talk about this often misunderstood phrase... The term RESTful APIs or RESTful services is a hot topic. So what is REST? And how do we create a so-called RESTful API? Good question! Let's talk about this often misunderstood phrase...
{{% notice style="tip" title="Here's a Quick Tip!" icon="exclamation-circle" %}} {{% notice info "A Loose Definition" %}}
When someone says, "REST service," "REST API" or "RESTful API" they more-than-likely mean an HTTP or Web-based server that accepts requests over HTTP and responds in human-readable JSON. When someone says, "REST service," "REST API" or "RESTful API" they more-than-likely mean an HTTP or Web-based server that accepts requests over HTTP and responds in human-readable JSON.
Yep, that really is it. But there are a lot of nuances--read on to discover more details! Yep, that really is it. But there are a lot of nuances--read on to discover more details!