Skip to content

Commit 362656a

Browse files
docs(api): Use correct HTTP method for specific issue (#13854)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR While going through the API docs page, I noticed that the example around mutating issues uses the POST method, but earlier on this docs page, it explicitly states that any endpoints whose purpose is to just update should be a PUT. Moreover, the endpoints in this example are real and there is no POST for them. ## IS YOUR CHANGE URGENT? No
1 parent 112bd53 commit 362656a

File tree

1 file changed

+5
-5
lines changed

1 file changed

+5
-5
lines changed

develop-docs/backend/api/design.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,24 +119,24 @@ POST /resources/{id}
119119

120120
### Batch Operations
121121

122-
Resources can get complicated when you need to expose batch operations vs single resource operations. For batch operations it is preferred to expose them as a `POST` request on the collection when possible.
122+
Resources can get complicated when you need to expose batch operations vs single resource operations. For batch operations it is preferred to expose them as a `PUT` request on the collection when possible.
123123

124124
Let's say for example we have an endpoint that mutates an issue:
125125

126126
```
127-
POST /api/0/organizations/{org}/issues/{issue}/
127+
PUT /api/0/organizations/{org}/issues/{issue}/
128128
```
129129

130130
When designing a batch interface, we simply expose it on the collection instead of the individual resource:
131131

132132
```
133-
POST /api/0/organizations/{org}/issues/
133+
PUT /api/0/organizations/{org}/issues/
134134
```
135135

136136
You may also need to expose selectors on batch resources, which can be done through normal request parameters:
137137

138138
```
139-
POST /api/0/organizations/{org}/issues/
139+
PUT /api/0/organizations/{org}/issues/
140140
{
141141
"issues": [1, 2, 3]
142142
}
@@ -237,7 +237,7 @@ Expanding responses allow us to include relational information on a resource wit
237237

238238
In general, endpoints should expose the fewest fields that will make the API usable in the general scenario. Doing one SQL request per API request is a good rule of thumb. To return information on a bounded relationship, endpoints should rely on the `expand` parameter. To return an unbounded relationship, it should be another endpoint.
239239

240-
To take an example, let's talk about the projects list endpoint. A project belongs to an organizations but could be on multiple teams.
240+
To take an example, let's talk about the projects list endpoint. A project belongs to an organization but could be on multiple teams.
241241

242242
By default, here's what the project endpoint should look like
243243

0 commit comments

Comments
 (0)