Introduction
The Example API is a RESTful web service that shows how Spring REST docs works. Interact with these endpoints in .
HTTP verbs
The Example API 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, overwrites all fields |
|
Used for partial updates to an existing resource |
|
Used to delete an existing resource |
HTTP status codes
The Example API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. For example,
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 |
|
The type of request for this resource is not allowed. For example, some endpoints may be GET only. Trying a POST will return this message. |
For more status codes, see the w3 standard
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 request’s timestamp |
|
|
The path that generated the error |
|
|
The human readable error message |
|
|
The HTTP status describing the error |
|
|
The short message describing the error |
For example, a request that attempts to delete on the greetings endpoint will produce a
405 Method Not Allowed
response:
Curl request
$ curl 'http://localhost:8080/greetings/' -i -X DELETE \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
HTTP request
DELETE /greetings/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: localhost:8080
HTTP response
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8
Content-Length: 183
{
"timestamp" : "2019-03-17T18:52:53.441+0000",
"path" : "/greetings/",
"status" : 405,
"error" : "Method Not Allowed",
"message" : "Request method 'DELETE' not supported"
}
Resources
Greetings
The greetings resource returns greetings for various inputs
List of Greetings
A `GET` request with no parameters will return a list of potential greetings
Curl request
$ curl 'http://localhost:8080/greetings/' -i \
-H 'Accept: application/json'
HTTP request
GET /greetings/ HTTP/1.1
Accept: application/json
Host: localhost:8080
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 132
[ {
"id" : "5c8e9747a5e6c5a91257c9bd",
"message" : "Hello!"
}, {
"id" : "5c8e9785a5e6c5a9334863de",
"message" : "Hello!"
} ]
Get by ID
A GET
request with a path parameter of the id will return the greeting with that id.
Curl request
$ curl 'http://localhost:8080/greetings/5c8e9785a5e6c5a9334863de' -i \
-H 'Accept: application/json'
HTTP request
GET /greetings/5c8e9785a5e6c5a9334863de HTTP/1.1
Accept: application/json
Host: localhost:8080
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 63
{
"id" : "5c8e9785a5e6c5a9334863de",
"message" : "Hello!"
}
Create a Custom Greeting
A POST
request will create new greetings.
Request fields
Path | Type | Description | Optional |
---|---|---|---|
message |
String |
The greeting’s message |
false |
Curl request
$ curl 'http://localhost:8080/greetings/' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"message" : "Hello!"
}'
HTTP request
POST /greetings/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080
Content-Length: 26
{
"message" : "Hello!"
}
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 63
{
"id" : "5c8e9785a5e6c5a9334863de",
"message" : "Hello!"
}