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

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

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

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

Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, e.g. application/hal+json

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

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

Number

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

{
  "error" : "Bad Request",
  "message" : "The tag 'http://localhost:8080/tags/123' does not exist",
  "status" : 400,
  "path" : "/notes",
  "timestamp" : 1665592064776
}

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

Object

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"
    }
  }
}
Relation Description

notes

The Notes resource

tags

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

_embedded.notes

Array

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

_embedded.tags

Array

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

Relation Description

self

This note

note-tags

This note’s tags

Retrieve a note

A GET request will retrieve the details of a note

Response fields

Path Type Description

title

String

The title of the note

body

String

The body of the note

_links

Object

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

Relation Description

self

This tag

tagged-notes

The notes that have this tag

Retrieve a tag

A GET request will retrieve the details of a tag

Response fields

Path Type Description

name

String

The name of the tag

_links

Object

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