= RESTful Notes Getting Started Guide
Andy Wilkinson;
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:

[[introduction]]
= Introduction

RESTful Notes is a RESTful web service for creating and storing notes. It uses hypermedia
to describe the relationships between resources and to allow navigation between them.



[[getting-started-running-the-service]]
== Running the service
RESTful Notes is written using https://projects.spring.io/spring-boot[Spring Boot] which
makes it easy to get it up and running so that you can start exploring the REST API.

The first step is to clone the Git repository:

[source,bash]
----
$ git clone https://github.com/spring-projects/spring-restdocs
----

Once the clone is complete, you're ready to get the service up and running:

[source,bash]
----
$ cd samples/rest-notes-spring-hateoas
$ ./gradlew build
$ java -jar build/libs/*.jar
----

You can check that the service is up and running by executing a simple request using
cURL:

include::{snippets}/index/1/curl-request.adoc[]

This request should yield the following response:

include::{snippets}/index/1/http-response.adoc[]

Note the `_links` in the JSON response. They are key to navigating the API.



[[getting-started-creating-a-note]]
== Creating a note
Now that you've started the service and verified that it works, the next step is to use
it to create a new note. As you saw above, the URI for working with notes is included as
a link when you perform a `GET` request against the root of the service:

include::{snippets}/index/1/http-response.adoc[]

To create a note you need to execute a `POST` request to this URI, including a JSON
payload containing the title and body of the note:

include::{snippets}/creating-a-note/1/curl-request.adoc[]

The response from this request should have a status code of `201 Created` and contain a
`Location` header whose value is the URI of the newly created note:

include::{snippets}/creating-a-note/1/http-response.adoc[]

To work with the newly created note you use the URI in the `Location` header. For example
you can access the note's details by performing a `GET` request:

include::{snippets}/creating-a-note/2/curl-request.adoc[]

This request will produce a response with the note's details in its body:

include::{snippets}/creating-a-note/2/http-response.adoc[]

Note the `note-tags` link which we'll make use of later.



[[getting-started-creating-a-tag]]
== Creating a tag
To make a note easier to find, it can be associated with any number of tags. To be able
to tag a note, you must first create the tag.

Referring back to the response for the service's index, the URI for working with tags is
include as a link:

include::{snippets}/index/1/http-response.adoc[]

To create a tag you need to execute a `POST` request to this URI, including a JSON
payload containing the name of the tag:

include::{snippets}/creating-a-note/3/curl-request.adoc[]

The response from this request should have a status code of `201 Created` and contain a
`Location` header whose value is the URI of the newly created tag:

include::{snippets}/creating-a-note/3/http-response.adoc[]

To work with the newly created tag you use the URI in the `Location` header. For example
you can access the tag's details by performing a `GET` request:

include::{snippets}/creating-a-note/4/curl-request.adoc[]

This request will produce a response with the tag's details in its body:

include::{snippets}/creating-a-note/4/http-response.adoc[]



[[getting-started-tagging-a-note]]
== Tagging a note
A tag isn't particularly useful until it's been associated with one or more notes. There
are two ways to tag a note: when the note is first created or by updating an existing
note. We'll look at both of these in turn.



[[getting-started-tagging-a-note-creating]]
=== Creating a tagged note
The process is largely the same as we saw before, but this time, in addition to providing
a title and body for the note, we'll also provide the tag that we want to be associated
with it.

Once again we execute a `POST` request, but this time, in an array named tags, we include
the URI of the tag we just created:

include::{snippets}/creating-a-note/5/curl-request.adoc[]

Once again, the response's `Location` header tells use the URI of the newly created note:

include::{snippets}/creating-a-note/5/http-response.adoc[]

As before, a `GET` request executed against this URI will retrieve the note's details:

include::{snippets}/creating-a-note/6/curl-request.adoc[]
include::{snippets}/creating-a-note/6/http-response.adoc[]

To see the note's tags, execute a `GET` request against the URI of the note's
`note-tags` link:

include::{snippets}/creating-a-note/7/curl-request.adoc[]

The response shows that, as expected, the note has a single tag:

include::{snippets}/creating-a-note/7/http-response.adoc[]



[[getting-started-tagging-a-note-existing]]
=== Tagging an existing note
An existing note can be tagged by executing a `PATCH` request against the note's URI with
a body that contains the array of tags to be associated with the note. We'll use the
URI of the untagged note that we created earlier:

include::{snippets}/creating-a-note/8/curl-request.adoc[]

This request should produce a `204 No Content` response:

include::{snippets}/creating-a-note/8/http-response.adoc[]

When we first created this note, we noted the `note-tags` link included in its details:

include::{snippets}/creating-a-note/2/http-response.adoc[]

We can use that link now and execute a `GET` request to see that the note now has a
single tag:

include::{snippets}/creating-a-note/9/curl-request.adoc[]
include::{snippets}/creating-a-note/9/http-response.adoc[]
