The following table shows the HTTP verbs, the scope, and the semantics for the methods that our new API must support. Each method is composed of an HTTP verb, a scope, and all the methods have well-defined meanings for all the resources and collections:
|
HTTP verb |
Scope |
Semantics |
|
|
Collection of message categories |
Retrieve all the stored message categories in the collection and return them sorted by their name in ascending order. Each category must include the full URL for the resource. Each category must include a list with all the details for the messages that belong to the category. The messages don't have to include the category in order to avoid repeating data. |
|
|
Message category |
Retrieve a single message category. The category must include the same information explained for each category when we retrieve a collection of message category. |
|
|
Collection of message categories |
Create a new message category in the collection. |
|
|
Message category |
Update the name of an existing message category. |
|
|
Message category
|
Delete an existing message category. |
|
|
Collection of messages |
Retrieve all the stored messages in the collection, sorted by their message in ascending order. Each message must include its message category details, including the full URL to access the related resource. The message category details don't have to include the messages that belong to the category. The message must include the full URL to access the resource. |
|
|
Message |
Retrieve a single message. The message must include the same information explained for each message when we retrieve a collection of messages. |
|
|
Collection of messages
|
Create a new message in the collection. |
|
|
Message |
Update any of the following fields of an existing message: message, duration, printed_times, and printed_once. |
|
|
Message |
Delete an existing message. |
In addition, our RESTful API must support the OPTIONS method for all the resources and collection of resources. We will use SQLAlchemy as our ORM and we will work with a PostgreSQL database. However, in case you don't want to spend time installing PostgreSQL, you can use any other database supported by SQLAlchemy, such as MySQL. In case you want the simplest database, you can work with SQLite.
In the preceding table, there are many methods and scopes. The following list enumerates the URIs for each scope mentioned in the preceding table, where {id} has to be replaced with the numeric id or primary key of the resource. As happened in the previous example, 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 and when we refer to a single resource of the collection, we won't use a slash (/) as the last character for the URL:
- Collection of message categories:
/categories/ - Message category:
/category/{id} - Collection of messages:
/messages/ - Message:
/message/{id}
Let's consider that http://localhost:5000/api/ is the URL for the API running on the Flask development server. We have to compose and send an HTTP request with the following HTTP verb (GET) and request URL (http://localhost:5000/api/categories/) to retrieve all the stored message categories in the collection. Each category will include a list with all the messages that belong to the category.
GET http://localhost:5000/api/categories/