Introduction

The Example API is a RESTful web service that shows how Spring REST docs works. Interact with these endpoints in Postman.

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

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, overwrites all fields

PATCH

Used for partial updates to an existing resource

DELETE

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

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

405 Method Not Allowed

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

timestamp

String

The request’s timestamp

path

String

The path that generated the error

message

String

The human readable error message

status

Number

The HTTP status describing the error

error

String

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!"
}