Understanding the tasks performed by each HTTP method

Let's consider that http://localhost:5000/service/notifications/ is the URL for the collection of notifications. If we add a number to the previous URL, we identify a specific notification whose ID is equal to the specified numeric value. For example, http://localhost:5000/service/notifications/5 identifies the notification whose ID is equal to 5.

We want our API to differentiate collections from a single resource of the collection in the URLs. When we refer to a collection, we will use a slash (/) as the last character for the URL, as in http://localhost:5000/service/notifications/. When we refer to a single resource of the collection, we won't use a slash (/) as the last character for the URL, as in http://localhost:5000/service/notifications/5.

We have to compose and send an HTTP request with the following HTTP verb (POST) and request URL (http://localhost:5000/service/notifications/) to create a new notification. In addition, we have to provide the JSON key-value pairs with the field names and the values to create the new notification. As a result of the request, the service will validate the values provided for the fields, making sure that it is a valid notification and persists it in the in-memory notifications dictionary. The service will return a 201 Created status code and a JSON body with the recently added notification serialized to JSON, including the assigned ID that was automatically generated by the service to the notification object:

POST http://localhost:5000/service/notifications/ 

We have to compose and send an HTTP request with the following HTTP verb (GET) and request URL (http://localhost:5000/service/notifications/{id}) to retrieve the notification whose ID matches the specified numeric value in the place where {id} is written. For example, if we use the http://localhost:5000/service/notifications/23 request URL, the service will retrieve the notification whose ID matches 23 from the dictionary. If a notification is found, the service will serialize the notification object into JSON and return a 200 OK status code and a JSON body with the serialized notification object. If no notification matches the specified ID or primary key, the service will return just a 404 Not Found status:

GET http://localhost:5000/service/notifications/{id} 

We have to compose and send an HTTP request with the following HTTP verb (PATCH) and request URL (http://localhost:5000/service/notifications/{id}) to update one or more fields for the notification whose ID matches the specified numeric value in the place where {id} is written. In addition, we have to provide the JSON key-value pairs with the field names to be updated and their new values. As a result of the request, the service will validate the values provided for the fields, update these fields on the notification that matches the specified ID, and update the notification in the dictionary if it is a valid notification. The service will return a 200 OK status code and a JSON body with the recently updated notification serialized to JSON. If we provide invalid data for the fields to be updated, the service will return a 400 Bad Request status code. If the service doesn't find a notification with the specified ID, the service will return just a 404 Not Found status:

PATCH http://localhost:5000/service/notifications/{id} 

The PATCH method will allow us to easily update two fields for a notification—the integer counter, which indicates the times the notification message has been printed, and the Boolean value, which specifies whether the notification message was printed at least once.

We have to compose and send an HTTP request with the following HTTP verb (DELETE) and request URL (http://localhost:5000/service/notifications/{id}) to remove the notification whose ID matches the specified numeric value in the place where {id} is written. For example, if we use the http://localhost:5000/service/notifications/27 request URL, the service will delete the notification whose ID matches 27. As a result of the request, the service will retrieve a notification with the specified ID from the dictionary. If a notification is found, the service will ask the dictionary to delete the entry associated with this notification object and the service will return a 204 No Content status code. If no notification matches the specified ID, the service will return just a 404 Not Found status.

DELETE http://localhost:5000/service/notifications/{id}