Overview
HTTP verbs
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.
Verb | Usage |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, including partial updates |
|
Used to delete an existing resource |
HTTP status codes
RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.
Status code | Usage |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
Headers
Every response has the following header(s):
Name | Description |
---|---|
|
The Content-Type of the payload, e.g. |
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
Path | Type | Description |
---|---|---|
|
|
The HTTP error that occurred, e.g. |
|
|
A description of the cause of the error |
|
|
The path to which the request was made |
|
|
The HTTP status code, e.g. |
|
|
The time, in milliseconds, at which the error occurred |
For example, a request that attempts to apply a non-existent tag to a note will produce a
400 Bad Request
response:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 172
{
"timestamp" : 1652723021267,
"path" : "/notes",
"status" : 400,
"message" : "The tag 'http://localhost:8080/tags/123' does not exist",
"error" : "Bad Request"
}
Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their
responses. Responses are in Hypertext
Application Language (HAL) format. Links can be found beneath the _links
key. Users of
the API should not create URIs themselves, instead they should use the above-described
links to navigate from resource to resource.
Resources
Index
The index provides the entry point into the service.
Accessing the index
A GET
request is used to access the index
Response fields
Path | Type | Description |
---|---|---|
|
|
Links to other resources |
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 155
{
"_links" : {
"notes" : {
"href" : "http://localhost:8080/notes"
},
"tags" : {
"href" : "http://localhost:8080/tags"
}
}
}
Links
Relation | Description |
---|---|
|
The Notes resource |
|
The Tags resource |
Notes
The Notes resources is used to create and list notes
Listing notes
A GET
request will list all of the service’s notes.
Response fields
Path | Type | Description |
---|---|---|
|
|
An array of Note resources |
Example request
$ curl 'http://localhost:8080/notes' -i -X GET
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1016
{
"_embedded" : {
"notes" : [ {
"title" : "REST maturity model",
"body" : "https://martinfowler.com/articles/richardsonMaturityModel.html",
"_links" : {
"self" : {
"href" : "http://localhost:8080/notes/7"
},
"note-tags" : {
"href" : "http://localhost:8080/notes/7/tags"
}
}
}, {
"title" : "Hypertext Application Language (HAL)",
"body" : "https://github.com/mikekelly/hal_specification",
"_links" : {
"self" : {
"href" : "http://localhost:8080/notes/8"
},
"note-tags" : {
"href" : "http://localhost:8080/notes/8/tags"
}
}
}, {
"title" : "Application-Level Profile Semantics (ALPS)",
"body" : "https://github.com/alps-io/spec",
"_links" : {
"self" : {
"href" : "http://localhost:8080/notes/9"
},
"note-tags" : {
"href" : "http://localhost:8080/notes/9/tags"
}
}
} ]
}
}
Creating a note
A POST
request is used to create a note.
Request fields
Path | Type | Description | Constraints |
---|---|---|---|
title |
String |
The title of the note |
Must not be blank |
body |
String |
The body of the note |
|
tags |
Array |
An array of tag resource URIs |
Example request
$ curl 'http://localhost:8080/notes' -i -X POST \
-H 'Content-Type: application/hal+json' \
-d '{
"title" : "REST maturity model",
"body" : "https://martinfowler.com/articles/richardsonMaturityModel.html",
"tags" : [ "http://localhost:8080/tags/10" ]
}'
Example response
HTTP/1.1 201 Created
Location: http://localhost:8080/notes/11
Tags
The Tags resource is used to create and list tags.
Listing tags
A GET
request will list all of the service’s tags.
Response fields
Path | Type | Description |
---|---|---|
|
|
An array of Tag resources |
Example request
$ curl 'http://localhost:8080/tags' -i -X GET
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 743
{
"_embedded" : {
"tags" : [ {
"name" : "REST",
"_links" : {
"self" : {
"href" : "http://localhost:8080/tags/4"
},
"tagged-notes" : {
"href" : "http://localhost:8080/tags/4/notes"
}
}
}, {
"name" : "Hypermedia",
"_links" : {
"self" : {
"href" : "http://localhost:8080/tags/5"
},
"tagged-notes" : {
"href" : "http://localhost:8080/tags/5/notes"
}
}
}, {
"name" : "HTTP",
"_links" : {
"self" : {
"href" : "http://localhost:8080/tags/6"
},
"tagged-notes" : {
"href" : "http://localhost:8080/tags/6/notes"
}
}
} ]
}
}
Creating a tag
A POST
request is used to create a note
Request fields
Path | Type | Description | Constraints |
---|---|---|---|
name |
String |
The name of the tag |
Must not be blank |
Example request
$ curl 'http://localhost:8080/tags' -i -X POST \
-H 'Content-Type: application/hal+json' \
-d '{
"name" : "REST"
}'
Example response
HTTP/1.1 201 Created
Location: http://localhost:8080/tags/12
Note
The Note resource is used to retrieve, update, and delete individual notes
Retrieve a note
A GET
request will retrieve the details of a note
Response fields
Path | Type | Description |
---|---|---|
|
|
The title of the note |
|
|
The body of the note |
|
|
Links to other resources |
Example request
$ curl 'http://localhost:8080/notes/14' -i -X GET
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 283
{
"title" : "REST maturity model",
"body" : "https://martinfowler.com/articles/richardsonMaturityModel.html",
"_links" : {
"self" : {
"href" : "http://localhost:8080/notes/14"
},
"note-tags" : {
"href" : "http://localhost:8080/notes/14/tags"
}
}
}
Update a note
A PATCH
request is used to update a note
Request structure
Path | Type | Description | Constraints |
---|---|---|---|
title |
String |
The title of the note |
Must be null or not blank |
body |
String |
The body of the note |
|
tags |
Array |
An array of tag resource URIs |
To leave an attribute of a note unchanged, any of the above may be omitted from the request.
Example request
$ curl 'http://localhost:8080/notes/2' -i -X PATCH \
-H 'Content-Type: application/hal+json' \
-d '{
"tags" : [ "http://localhost:8080/tags/3" ]
}'
Example response
HTTP/1.1 204 No Content
Tag
The Tag resource is used to retrieve, update, and delete individual tags
Retrieve a tag
A GET
request will retrieve the details of a tag
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the tag |
|
|
Links to other resources |
Example request
$ curl 'http://localhost:8080/tags/15' -i -X GET
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 192
{
"name" : "REST",
"_links" : {
"self" : {
"href" : "http://localhost:8080/tags/15"
},
"tagged-notes" : {
"href" : "http://localhost:8080/tags/15/notes"
}
}
}
Update a tag
A PATCH
request is used to update a tag
Request fields
Path | Type | Description | Constraints |
---|---|---|---|
name |
String |
The name of the tag |
Must be null or not blank |
Example request
$ curl 'http://localhost:8080/tags/1' -i -X PATCH \
-H 'Content-Type: application/hal+json' \
-d '{
"name" : "RESTful"
}'
Example response
HTTP/1.1 204 No Content