Use default location for .adoc source in Gradle-based sample
Previously both samples supported Maven and Gradle. Due to the different default locations between the two build systems, the Gradle-based sample was configured to use Maven’s default location for its .adoc files. The samples have now been updated so that one sample uses Maven and the other uses Gradle. However, when this change was made, the customization of the Gradle-based sample’s .adoc file location wasn’t removed. This commit updates the Gradle-based sample to use the default location, src/docs/asciidoc, for its .adoc source files. Closes gh-145
This commit is contained in:
Andy Wilkinson
@@ -1,315 +0,0 @@
|
||||
= RESTful Notes API Guide
|
||||
Andy Wilkinson;
|
||||
:doctype: book
|
||||
:icons: font
|
||||
:source-highlighter: highlightjs
|
||||
:toc: left
|
||||
:toclevels: 4
|
||||
:sectlinks:
|
||||
|
||||
[[overview]]
|
||||
= Overview
|
||||
|
||||
[[overview-http-verbs]]
|
||||
== 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
|
||||
|===
|
||||
|
||||
[[overview-http-status-codes]]
|
||||
== 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
|
||||
|===
|
||||
|
||||
[[overview-headers]]
|
||||
== Headers
|
||||
|
||||
Every response has the following header(s):
|
||||
|
||||
include::{snippets}/headers-example/response-headers.adoc[]
|
||||
|
||||
[[overview-errors]]
|
||||
== 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:
|
||||
|
||||
include::{snippets}/error-example/response-fields.adoc[]
|
||||
|
||||
For example, a request that attempts to apply a non-existent tag to a note will produce a
|
||||
`400 Bad Request` response:
|
||||
|
||||
include::{snippets}/error-example/http-response.adoc[]
|
||||
|
||||
[[overview-hypermedia]]
|
||||
== Hypermedia
|
||||
|
||||
RESTful Notes uses hypermedia and resources include links to other resources in their
|
||||
responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
|
||||
from resource to resource.
|
||||
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
|
||||
|
||||
[[resources]]
|
||||
= Resources
|
||||
|
||||
|
||||
|
||||
[[resources-index]]
|
||||
== Index
|
||||
|
||||
The index provides the entry point into the service.
|
||||
|
||||
|
||||
|
||||
[[resources-index-access]]
|
||||
=== Accessing the index
|
||||
|
||||
A `GET` request is used to access the index
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{snippets}/index-example/response-fields.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/index-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-index-links]]
|
||||
==== Links
|
||||
|
||||
include::{snippets}/index-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-notes]]
|
||||
== Notes
|
||||
|
||||
The Notes resources is used to create and list notes
|
||||
|
||||
|
||||
|
||||
[[resources-notes-list]]
|
||||
=== Listing notes
|
||||
|
||||
A `GET` request will list all of the service's notes.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{snippets}/notes-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/notes-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/notes-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-notes-create]]
|
||||
=== Creating a note
|
||||
|
||||
A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/notes-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/notes-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/notes-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-tags]]
|
||||
== Tags
|
||||
|
||||
The Tags resource is used to create and list tags.
|
||||
|
||||
|
||||
|
||||
[[resources-tags-list]]
|
||||
=== Listing tags
|
||||
|
||||
A `GET` request will list all of the service's tags.
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{snippets}/tags-list-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/tags-list-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/tags-list-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-tags-create]]
|
||||
=== Creating a tag
|
||||
|
||||
A `POST` request is used to create a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/tags-create-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/tags-create-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/tags-create-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-note]]
|
||||
== Note
|
||||
|
||||
The Note resource is used to retrieve, update, and delete individual notes
|
||||
|
||||
|
||||
|
||||
[[resources-note-links]]
|
||||
=== Links
|
||||
|
||||
include::{snippets}/note-get-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-note-retrieve]]
|
||||
=== Retrieve a note
|
||||
|
||||
A `GET` request will retrieve the details of a note
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{snippets}/note-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/note-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/note-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-note-update]]
|
||||
=== Update a note
|
||||
|
||||
A `PATCH` request is used to update a note
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/note-update-example/request-fields.adoc[]
|
||||
|
||||
To leave an attribute of a note unchanged, any of the above may be omitted from the request.
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/note-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/note-update-example/http-response.adoc[]
|
||||
|
||||
|
||||
[[resources-tag]]
|
||||
== Tag
|
||||
|
||||
The Tag resource is used to retrieve, update, and delete individual tags
|
||||
|
||||
|
||||
|
||||
[[resources-tag-links]]
|
||||
=== Links
|
||||
|
||||
include::{snippets}/tag-get-example/links.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-tag-retrieve]]
|
||||
=== Retrieve a tag
|
||||
|
||||
A `GET` request will retrieve the details of a tag
|
||||
|
||||
==== Response structure
|
||||
|
||||
include::{snippets}/tag-get-example/response-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/tag-get-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/tag-get-example/http-response.adoc[]
|
||||
|
||||
|
||||
|
||||
[[resources-tag-update]]
|
||||
=== Update a tag
|
||||
|
||||
A `PATCH` request is used to update a tag
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/tag-update-example/request-fields.adoc[]
|
||||
|
||||
==== Example request
|
||||
|
||||
include::{snippets}/tag-update-example/curl-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/tag-update-example/http-response.adoc[]
|
||||
@@ -1,176 +0,0 @@
|
||||
= 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]
|
||||
= Getting started
|
||||
|
||||
|
||||
|
||||
[getting-started-running-the-service]
|
||||
== Running the service
|
||||
RESTful Notes is written using http://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[]
|
||||
Reference in New Issue
Block a user