Contributing to the Microsoft REST API Guidelines

The Microsoft REST API Guidelines is a Microsoft-wide initiative to develop consistent design guidelines for REST APIs. The initiative requires input and feedback from a variety of individuals both inside and outside of Microsoft.

To provide feedback, please follow the guidance in this document. Please note that these are just guidelines, not rules. Use your best judgment and feel free to propose changes to anything in this repository, including the contribution guidance.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Creating issues
Documentation styleguide
Commit messages
Pull requests

Creating issues

You can create an issue, but before doing that please read the bullets below and include as many details as possible.
Perform a cursory search to see if a similar issue has already been submitted.
Reference the version of the Microsoft REST API Guidelines you are using.
Include the guidance you expected and other places you've seen that guidance, e.g. White House Web API Standards.
Include sample requests and responses whenever possible.

Related repositories

This is the repository for Microsoft REST API Guidelines documentation only. Please ensure that you are opening issues in the right repository.

Recommended setup for contributing

Install Atom, VS Code, or your favorite editor
Install markdown-toc package

Documentation styleguide

Use GitHub-flavored markdown
Use syntax-highlighted examples liberally
Trim trailing empty lines from HTTP requests
Retain only essential headers for understanding the example
Use valid (e.g., member names quoted), pretty-printed JSON with a 2 space indent
Minimize JSON payloads by using ellipses
Write one sentence per line.

Example

Request

GET http://services.odata.org/V4/TripPinServiceRW/People HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@nextLink":"http://services.odata.org/V4/TripPinServiceRW/People?$skiptoken=8",
  "value":[
    {
      "userName":"russellwhyte",
      "firstName":"Russell",
      "lastName":"Whyte",
      "emails":[
        "Russell@example.com",
        "Russell@contoso.com"
      ],
      "addressInfo":[
        {
          "address":"187 Suffolk Ln.",
          "city":{
            "countryRegion":"United States",
            "name":"Boise",
            "region":"ID"
          }
        }
      ],
      "gender":"Male",
    },
    ...
  ]
}

Commit messages

Use the present tense: "Change ...", not "Changed ..."
Use the imperative mood: "Change ...", not "Changes ..."
Limit the first line to 72 characters or less
Reference issues and pull requests liberally

Pull requests

Pull requests serve as the primary mechanism by which contributions are proposed and accepted. We recommend creating a topic branch and sending a pull request to the master branch from the topic branch. For additional guidance, read through the GitHub Flow Guide.

Be prepared to address feedback on your pull request and iterate if necessary.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!