microsoft / microsoft/api-guidelines

Response body is optional and can be returned.

Open
#444 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.