add api guide
This commit is contained in:
Loredana Crusoveanu
parent
630acd7959
commit
3d233f5ede
|
|
@ -0,0 +1,195 @@
|
|||
= RESTful Notes API Guide
|
||||
Baeldung;
|
||||
: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
|
||||
|===
|
||||
|
||||
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-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
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/index-example/http-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/index-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/index-example/curl-request.adoc[]
|
||||
|
||||
[[resources-index-links]]
|
||||
==== Links
|
||||
|
||||
include::{snippets}/index-example/links.adoc[]
|
||||
|
||||
|
||||
[[resources-CRUD]]
|
||||
== CRUD REST Service
|
||||
|
||||
The CRUD provides the entry point into the service.
|
||||
|
||||
[[resources-crud-get]]
|
||||
=== Accessing the crud GET
|
||||
|
||||
A `GET` request is used to access the CRUD read.
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/crud-get-example/http-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/crud-get-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/crud-get-example/curl-request.adoc[]
|
||||
|
||||
[[resources-crud-post]]
|
||||
=== Accessing the crud POST
|
||||
|
||||
A `POST` request is used to access the CRUD create.
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/crud-create-example/http-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/crud-create-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/crud-create-example/curl-request.adoc[]
|
||||
|
||||
[[resources-crud-delete]]
|
||||
=== Accessing the crud DELETE
|
||||
|
||||
A `DELETE` request is used to access the CRUD delete.
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/crud-delete-example/http-request.adoc[]
|
||||
|
||||
==== Path Parameters
|
||||
include::{snippets}/crud-delete-example/path-parameters.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/crud-delete-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/crud-delete-example/curl-request.adoc[]
|
||||
|
||||
[[resources-crud-patch]]
|
||||
=== Accessing the crud PATCH
|
||||
|
||||
A `PATCH` request is used to access the CRUD update.
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/crud-patch-example/http-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/crud-patch-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/crud-patch-example/curl-request.adoc[]
|
||||
|
||||
[[resources-crud-put]]
|
||||
=== Accessing the crud PUT
|
||||
|
||||
A `PUT` request is used to access the CRUD update.
|
||||
|
||||
==== Request structure
|
||||
|
||||
include::{snippets}/crud-put-example/http-request.adoc[]
|
||||
|
||||
==== Example response
|
||||
|
||||
include::{snippets}/crud-put-example/http-response.adoc[]
|
||||
|
||||
==== CURL request
|
||||
|
||||
include::{snippets}/crud-put-example/curl-request.adoc[]
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue