This repository has been archived by the owner on Nov 8, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 61
/
api.apib
157 lines (89 loc) · 3.43 KB
/
api.apib
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
FORMAT: 1A
# Gist Fox API
Gist Fox API is a sample **pastes service** similar to [GitHub's Gist](http://gist.github.com).
## Media Types
Where applicable this API uses the [HAL+JSON](http://stateless.co/hal_specification.html) media type to represent resources, states and affordances.
Request bodies are using plain JSON to create new resources. Bodies of the PATCH requests are processed according to [RFC7396](https://tools.ietf.org/html/rfc7396).
## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.
## Gist Fox API Root [/]
Gist Fox API entry point. Provides initial API affordances in the form of the HTTP Link header and HAL links.
### Retrieve the Entry Point [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http://api.example.com/>;rel="self",<http://api.example.com/gists>;rel="gists"
+ Attributes (Links)
## Gist [/gists/{id}]
A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.
+ Parameters
+ id: 42 (required, string) - ID of the Gist
### Retrieve a Single Gist [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http://api.example.com/gists/42>;rel="self", <http://api.example.com/gists/42/star>;rel="star"
+ Attributes (Gist)
### Edit a Gist [PATCH]
+ Request (application/json)
+ Attributes
+ content: `Updated content...`
+ Response 200 (application/hal+json)
+ Headers
Link: <http://api.example.com/gists/42>;rel="self", <http://api.example.com/gists/42/star>;rel="star"
+ Attributes (Gist)
### Delete a Gist [DELETE]
+ Response 204
## Gists Collection [/gists{?since}]
Collection of Gists.
+ Parameters
+ since: 0 (optional, number) - Timestamp in unix time format. Only Gists updated at or after this time are returned.
### List All Gists [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http://api.example.com/gists>;rel="self"
+ Attributes (Gists Collection)
### Create a Gist [POST]
+ Request (application/json)
+ Attributes
+ description: `Gist description...`
+ content: `String content...`
+ Response 201 (application/hal+json)
+ Headers
Link: <http://api.example.com/gists/42>;rel="self", <http://api.example.com/gists/42/star>;rel="star"
+ Attributes (Gist)
## Star [/gists/{id}/star]
Gist's starred status.
+ Parameters
+ id: 42 (required, string) - ID of the Gist
### Star a Gist [PUT]
+ Response 204
### Unstar a Gist [DELETE]
+ Response 204
### Check If a Gist Is Starred [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http://api.example.com/gists/42/star>;rel="self"
+ Attributes (Star)
## Data Structures
## Gist
A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.
- id: `42`
- created_at: `2016-04-14T02:15:15Z`
- description: `Gist description...`
- content: `String content...`
- Include Links
## Gists Collection
Collection of Gists.
- _embedded
- gists (array[Gist])
- total (number) - Total number of listed Gists.
- Include Links
## Star
Gist's starred status.
- starred (boolean)
- Include Links
## Links
HAL links.
- _links
- *self*
- href - URL
- templated (boolean) - Whether the respective URL uses URI Templates