microsoft / microsoft/api-guidelines
Response body is optional and can be returned.
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 23.3k
- Forks
- 2.7k
- PR merge metrics
- No merged PRs in 30d
Description
**_13.2.1. PUT
Services MAY enable PUT requests for entity creation.
PUT https://api.contoso.com/v1.0/databases/db1
In this scenario the databases segment is processing the PUT operation.
HTTP/1.1 202 Accepted
Operation-Location: https://api.contoso.com/v1.0/operations/123
For services that need to return a 201 Created here, use the hybrid flow described below.
The 202 Accepted should return no body. The 201 Created case should return the body of the target resource._**
Please find additional notes that body is optional:
According to the HTTP/1.1 specification (RFC 7231), the 202 Accepted status code is optional when it comes to including a response body. The decision to include a response body depends on the specific use case and the API design.
When you choose to include a response body with a 202 Accepted response, it is typically used to provide additional information about the ongoing process or to give details on how to track the progress of the operation. This might include a status message or a reference to a resource that provides the current status of the operation.
If you decide to include a response body, it is important to ensure that the response is properly documented in your API documentation so that clients know what to expect and how to handle the response.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with section 13.2.1, “PUT,” in the API guidelines and compare its 202 Accepted and 201 Created examples with RFC 7231. Clarify that a 202 response body is optional and explain what clients should expect when one is included; the updated guideline text is the completion criterion.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100