-
Notifications
You must be signed in to change notification settings - Fork 730
/
api-guide.md.erb
206 lines (116 loc) · 7.22 KB
/
api-guide.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
---
title: REST Notes API Guide
language_tabs:
- shell
- http
search: true
---
# 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
## Errors
<%= ERB.new(File.read("../build/generated-snippets/error-example/http-response.md")).result(binding) %>
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:
<%= ERB.new(File.read("../build/generated-snippets/error-example/response-fields.md")).result(binding) %>
## Hypermedia
RESTful Notes uses hypermedia and resources include links to other resources in their
responses. Responses are in [Hypertext Application Language (HAL)](http://stateless.co/hal_specification.html 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
## Index
<%= ERB.new(File.read("../build/generated-snippets/index-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-response.md")).result(binding) %>
The index provides the entry point into the service. A `GET` request is used to access the index.
### Response structure
<%= ERB.new(File.read("../build/generated-snippets/index-example/response-fields.md")).result(binding) %>
### Links
<%= ERB.new(File.read("../build/generated-snippets/index-example/links.md")).result(binding) %>
## Notes
The Notes resources is used to create and list notes
### Listing notes
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/http-response.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/curl-request.md")).result(binding) %>
A `GET` request will list all of the service's notes.
#### Response structure
<%= ERB.new(File.read("../build/generated-snippets/notes-list-example/response-fields.md")).result(binding) %>
### Creating a note
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/curl-request.md")).result(binding) %>
A `POST` request is used to create a note
#### Request structure
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/request-fields.md")).result(binding) %>
## Tags
The Tags resource is used to create and list tags.
### Listing tags
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/http-response.md")).result(binding) %>
A `GET` request will list all of the service's tags.
#### Response structure
<%= ERB.new(File.read("../build/generated-snippets/tags-list-example/response-fields.md")).result(binding) %>
### Creating a tag
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/notes-create-example/http-response.md")).result(binding) %>
A `POST` request is used to create a tag
#### Request structure
<%= ERB.new(File.read("../build/generated-snippets/tags-create-example/request-fields.md")).result(binding) %>
## Note
The Note resource is used to retrieve, update, and delete individual notes
### Retrieve a note
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/http-response.md")).result(binding) %>
A `GET` request will retrieve the details of a note
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/response-fields.md")).result(binding) %>
#### Links
<%= ERB.new(File.read("../build/generated-snippets/note-get-example/links.md")).result(binding) %>
### Update a note
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/http-response.md")).result(binding) %>
A `PATCH` request is used to update a note
#### Request structure
<%= ERB.new(File.read("../build/generated-snippets/note-update-example/request-fields.md")).result(binding) %>
To leave an attribute of a note unchanged, any of the above may be omitted from the
request.
## Tag
The Tag resource is used to retrieve, update, and delete individual tags
### Retrieve a tag
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/http-response.md")).result(binding) %>
A `GET` request will retrieve the details of a tag
#### Response structure
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/response-fields.md")).result(binding) %>
#### Links
<%= ERB.new(File.read("../build/generated-snippets/tag-get-example/links.md")).result(binding) %>
### Update a tag
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/http-response.md")).result(binding) %>
A `PATCH` request is used to update a tag
#### Request structure
<%= ERB.new(File.read("../build/generated-snippets/tag-update-example/request-fields.md")).result(binding) %>