microsoft / api-guidelines

Microsoft REST API Guidelines

Microsoft REST API Guidelines

Thank you for your interest in the Microsoft REST API Guidelines. If you have landed here, you're probably interested in learning about APIs. If so, you are in the right place! We publish these guidelines here with the aim of fostering dialogue and learning in the API community at large. We further hope that these guidelines might encourage other organizations to create guidelines that are appropriate for them and in turn, if they're able, to publish theirs.

Guidance for Azure service teams

Azure service teams should reference the companion documents, Azure REST API Guidelines and Considerations for Service Design, when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information, please refer to the README in the Azure folder.

Guidance for Microsoft Graph service teams

Graph service teams should reference the companion document, Microsoft Graph REST API Guidelines when building or modifying their services. This document and the associated pattern catalog provide a refined set of guidance targeted specifically for Microsoft Graph services.

Code of Conduct

This project adopts the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

This repository

This repository contains a collection of documents and related materials supporting the overall Microsoft REST API Guidelines initiative. To contribute to this repository, see the contribution guidelines.

api-guidelines's Issues

OPTIONS must be idempotent

Per RFC 7231, OPTIONS is defined as a safe method. RFC 7231 also states all safe methods are idempotent, hence OPTIONS must be idempotent.

Section 7.4 Supported Verbs should really be Supported Methods

Although it is common practice to use the phrase HTTP verb, it is inconsistent with the HTTP specification, the .net framework and the IANA Method Registry.

Although most experienced developers will know that verb and method is synonymous in the case of HTTP, this introduces a potential for confusion for new developers.

Hyphens or underscores in URLs?

Currently there is no guidance in the guidelines whether hyphens or underscore are preferred to connect words within a URL component.
Is that because you are undecided or do you explicitly not want to make a recommendation?

URL path camelCase vs underscore vs dash etc.

It would be great if the standards document expressed a clear opinion on how multiple words should be concatenated in URL path segments.

For example:

https://api.contoso.com/v1.0/pullRequests
https://api.contoso.com/v1.0/pull-requests
https://api.contoso.com/v1.0/pull_requests
https://api.contoso.com/v1.0/pullrequests

Versioning via headers?

Section 12.1 - Versioning Formats only discusses passing a version on the URL, either in the path or in the querystring.

It is also very common to pass an API version via HTTP headers instead, either via custom headers, or as part of Accept and Content-Type headers (aka, Media Type Versioning). These are both described in this guidance.

IMHO, these approaches should be mentioned, whether acceptable or unacceptable. Currently, there is no mention of them.

13.2.7.1 Long Running Operations.

In 13.2.7.1, the user is told to POST to one URl and then poll another URl to see whether the operation has completed.

The initial URl uses 202 to indicate that the request has been received. The subsequent URl responds with

Server responds that results are still not ready and optionally provides a recommendation to wait 30 seconds.

HTTP/1.1 200 OK
Retry-After: 30

I would understand 200 to mean that the request was accepted and completed.

Would it make more sense to use a code like 102 Processing?

The 102 (Processing) status code is an interim response used to
inform the client that the server has accepted the complete request,
but has not yet completed it. This status code SHOULD only be sent
when the server has a reasonable expectation that the request will
take significant time to complete. As guidance, if a method is taking
longer than 20 seconds (a reasonable, but arbitrary value) to process
the server SHOULD return a 102 (Processing) response. The server MUST
send a final response after the request has been completed.

Or, perhaps, continue sending 202 until the request is completed.

Section 11.3.2: the date used in the example does not match its description

The date written in the example is 2015-02-15T13:15Z but two lines before this date is introduced as "February 13, 2015, at 1:15 p.m. UTC"

Unsupported section is contradictory to HTTP status code 501

The section on Unsupported says to return an error response and a 4xx result unless there is a more specific code. But that is what HTTP 501 is designed for in my opinion. If something is not supported then 501 is the correct response to let the client know they are trying to call something that is not implemented (but perhaps could be in the future).

HTTP Status codes are missing

The HTTP Status codes are referenced but a recommendation is not defined anywhere.

Here's a good example.

https://brockallen.com/2012/05/14/http-status-codes-for-rest/

Response code 409 instead of 404 when PATCHing against nonexisting resource?

The guidline mentions this:

If a service does not support UPSERT, then a PATCH call against a resource that does not exist MUST result in an HTTP "409 Conflict" error.

In the refered RFC 5789 there is this:

Resource not found: Can be specified with a 404 (Not Found) status
code when the client attempted to apply a patch document to a non-
existent resource, but the patch document chosen cannot be applied
to a non-existent resource.

I think this should be clarified, and the following should be added (according to RFC 5789):

Conflicting state: Can be specified with a 409 (Conflict) status
code when the request cannot be applied given the state of the
resource. For example, if the client attempted to apply a
structural modification and the structures assumed to exist did
not exist (with XML, a patch might specify changing element 'foo'
to element 'bar' but element 'foo' might not exist).

GET urls often fail to meet the relevant spec standards

For example,

GET https://api.contoso.com/v1.0/people?$filter=name eq 'david'&$orderBy=hireDate

In this example, the success of this request is contingent on the HTTP client replacing with%20. Are you sure that's what you mean here? I notice also you don't make mention of potential SQL injection and similar issues arising from such a request-driven-dsl in this case.

Question about 8.2: Why query parameters, not Authorization header?

It is written that:

For GET and HEAD calls, avoid requiring request headers that are not part of the simple set above. Allow them to be provided as query parameters instead. The Authorization header is not part of the simple set, so the authentication token MUST be sent through the "access_token" query parameter instead, for resources requiring authentication.

As I understood, I MUST use the query parameters as a way to send access tokens. The question is: how are you going to get and validate your token, e.g. in Node JS using JWT, via query parameters? Isn't it much more secure and simpler to rather use Authorization header, than query parameters?

I may have missed something, hence this question may sound dumb.

PS. Or, is it related only to CORS preflight requests?

Thanks anyway!

Potential alternative to the new "Operation-Location" header

ref: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#1321-put

For long running operations that return 202, it is suggested to use Operation-Location to refer to a resource that can be monitored to determine when the requested operation is complete. Although, not explicitly specified by the HTTP spec, it is common practice to use the Location header to point to this status monitoring resource. See RFC7240 and RESTful Web Services Cookbook

It would seem prudent to follow common practice and avoid creating a new non-standard header for something that is commonly done.

For the hybrid scenario where the Location header is used to refer to the partially created resource and the Operation-Location header is used to point to the status resource, an alternative would be the following response:

HTTP/1.1 202 Accepted
Location: https://api.contoso.com/v1.0/operations/123
Content-Location: https://api.contoso.com/v1.0/databases/db1
{
  "databaseName": "db1",
  "color": "red",
  "Status": "Provisioning",
  [ … other fields for "database" …]
}

This approach is consistent with it's use of 202 to indicate that the creation process has not completed. It continues to use the Location header to indicate the location of the status monitoring resource. However, it also uses the Content-Location header to indicate that there is a response body that represents the current state of the resource being created and provides a URL to the final destination of the resource.

This approach provides equivalent functionality but doesn't require inventing a new header, it follows current common practices and it avoids having to impose the rules that the hybrid 201 must a have a
body, and it must indicate that it is incomplete, and that 202 responses shouldn't return a body.

Feedback on PATCH

Unfortunately i did not see any guidlines, how one should remove any fielddata from an object using PATCH or PUT.

Should Patch only support additive, atomic modifications?

I did some research and found JSON MERGE PATCH
JSON Merge Patch RFC

PATCH /target HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json
{
"a":"z",
"c": {
"f": null
}

Or there is another way, using the older JSON PATCH RFC

[
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
]

Which should be the preferred way to remove data from an object?

Difference between branches master and vNext

The default branch on GitHub is currently set to vNext if I'm not mistaken.

Is there a difference between master and vNext? Is master obsolete, vNext a work-in-progress and still to be validated, ...?

Section 8.2 of Guidelines.md: JSON-P linked website is actually a parked domain

The referenced website http://www.json-p.org/ hosts the classic "domain for sale" page.

Specify the license

How are these guidelines licensed? Proprietary or Creative Commons or ...?

Question about section 9.3.1 nested collections and properties

This is the example in the current guidelines:

GET https://api.contoso.com/v1.0/people/123/addresses

{
  "value": [
    { "street": "1st Avenue", "city": "Seattle" },
    { "street": "124th Ave NE", "city": "Redmond" }
  ]
}

Now let's say I need to have an API which returns a collection of <person, addresses> for all the people.

Assuming that I have only 2 people "100" and "101", the sample response would be:

[
  {
    "id": "100",
    "value": [
      { "street": "Lombard Street", "city": "San Francisco" }
    ]
  },
  {
    "id": "101",
    "value": [
      { "street": "1st Avenue", "city": "Seattle" },
      { "street": "124th Ave NE", "city": "Redmond" }
    ]
  }
]

What should the url for this be?

7.4.4 Link header example value is incorrect

Hi,

The Link header value is defined as "<" URI-Reference ">" *( ";" link-param ) by rfc5988, the current value form uses {help} instead of </help>. I assume the URI for help is meant to be relative to root, as defined by https://tools.ietf.org/html/rfc3987#section-3.1

Is the following:

Link: {help}; rel="help"

Probably should be:

Link: </help>; rel="help"

Including a link to the IANA reference might be useful for people getting started with correct hypermedia links: http://www.iana.org/assignments/link-relations/link-relations.xhtml

Cheers

Date Headers

Two issues:

1. Date is listed as both a standard request and response header (7.5/7.6), but this is typically found only as a response header. The HTTP spec (RFC 7231 § 7.1.1.2) states:

   A user agent MAY send a Date header field in a request, though generally will not do so unless it is believed to convey useful information to the server. For example, custom applications of HTTP might convey a Date if the server is expected to adjust its interpretation of the user's request based on differences between the user agent and server clocks.

2. In both places, the description says that the Date header is in RFC 3339 format, which is incorrect. Unfortunately, the HTTP spec doesn't use RFC 3339. It uses the older format found in RFC 5322 § 3.3 (previously listed under RFC 2822 and RFC 822)

   Example:

   Date:Wed, 03 Aug 2016 20:54:19 GMT
   

Let me know if you'd like a PR for this. Thanks.

Consideration: Breaking standards into separate markdown files?

The standards are long and extensive, covering many areas of an API. Is there any consideration worth making to split into multiple files, perhaps one per chapter? Especially since you can use build tools to combine + publish a final spec file. This may make it easier to manage the document in the longer term.

camelCase vs PascalCase for string enumerations

In documentation at https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#710-response-formats we can see
...

Property	Type	Required	Description
code	String (enumerated)	✔	One of a server-defined set of error codes.
...

{
  "error": {
    "code": "BadArgument",
    "message": "Previous passwords may not be reused",
    "target": "password",
    "innererror": {
      "code": "PasswordError",
      "innererror": {
        "code": "PasswordDoesNotMeetPolicy",
        "minLength": "6",
        "maxLength": "64",
        "characterTypes": ["lowerCase","upperCase","number","symbol"],
        "minDistinctCharacterTypes": "2",
        "innererror": {
          "code": "PasswordReuseNotAllowed"
        }
      }
    }
  }
}

Here property code is PascalCase'd as "BadArgument". and property characterTypes as camelCase'd.

This seems a bit confusing, since characterTypes seems to be enumeration of some sort, so why do they use camelCase but code use PascalCase?

Is there a guideline from Microsoft what casing enumerated string values should have? Is it PascalCase that is recommended?

Thanks.

When creating a resource that returns an empty body, should 201 or 204 win?

It feels like to me that a 201 should win as a client can always look at the content-length to know there is no body.

However, in the section on managing webhook subscriptions, the guidelines say:

The service MUST return an empty body and 204 No Content to indicate a successful patch

If we apply this rigidly, it means that if the subscription API supported "upserts" then we wouldn't be able to return a 201 to indicate creation.

Rethink some concepts having the existing jsonapi

I liked this repository just with one reason, somebody decided to create more or less readable guideline, which I can recommend to others(besides the using it myself). In the same time, we have http://jsonapi.org/, which is working and stable specification. And very reliable.

Here, I would like to suggest you to review it and merge if possible. Otherwise, most of guidelines are covered by "Restful web apis" book. To have one more interpretation of the output format is not really a contribution, in this case it produces destructful effect rather than positive.

Nevertheless, thank you for the engagement.

@nextLink vs. nextLink

Hi,

The guidelines describe that collections should have a @nextLink attribute.

However, in practice some Microsoft services use nextLink (without @).
See https://azure.github.io/projects/apis/#!/DeploymentOperations/DeploymentOperations_List for example.

What is preferred? I can expect the @ can make it harder to work with the model in JavaScript or when (de)serializing in .NET.

how to identify canonical URIs (section 7.3)

what about recommending that resources specifying canonical URIs should do so using the "canonical" link relation type as specified in https://tools.ietf.org/html/rfc6596? that would help to make those canonical links more easily discoverable across APIs.

Many parts of the guidelines are in all caps

I'm aware of RFC2119 which recommends to capitalize certain key words but was wondering if there's also a reason to all capitalize for example headings and the table of contents?

If there is no greater reason, I would vote to either Title case or Start Case the guidelines to increase readability and make them more friendly to the eyes of the reader.

Accept: being optional

Which HTTP guidelines specify that the content-types preferred by the client in the Accept: header are optional? I can't find anything to support that assertion. The header itself is optional, but as far as I know the server should either comply with the client's request, or return 406 Not Acceptable.

Questions: Are there any existing query string parser for suggested filter operations in section 9.7.1 ?

Partial URLs in 201 Created Location header?

In 7.4.1 you encourage the use of the Location header. Is there any policy/rule regarding using a full URL versus only the URL path?

I also suggest to make the guideline more verbose regarding my question, as it's often slightly inconvenient to respond with the full URL, and I can imagine a lot of people would prefer to have a shorter alternative.

Bug: Example GET request/response in 9.3.1 seems wrong

GET https://api.contoso.com/v1.0/people/123/addresses is shown as an example and returns a people entity back. Either the request should not have "addresses" or the response should show the addresses collection.

Question regarding $top

I have a question on the $top URL parameter, which first appears in Section 9.8.2 - Client-driven paging. How is this parameter defined and what is its relation with the $maxpagesize parameter (appearing in Section 9.8.3 - Additional Considerations).

Suggestion: Machine readable version

Are there any plans to provide a machine readable version of these guidelines so that it's possible to auto generate compliance tests (or possibly documentation/client code)?

Question: Validation tool / Compliance tests

Are their any validation tools or compliance test suites available to verify that an API follows these guidelines?

Grouping this repository

This repository should be in a ASP.NET repository group.

Response format of single entity

When returning a collection, the format looks like { value: [ ... ], ... }. When returning a single entity, it's not made clear whether it should also be returned as { value: { ... } } or just { ... }.

Some of the examples hint at returning { ... } directly, but it's not explicitly stated.

RFC 2616 is obsolete

as https://tools.ietf.org/html/rfc2616 shows, RFC 2616 has been obsoleted by a set of newer RFCs a while ago. @mnot has an excellent post about this at https://www.mnot.net/blog/2014/06/07/rfc2616_is_dead, which is already 2 years old. it will not be trivial to remove all RFC 2616 references from the guidelines, but it should be done better sooner than later since HTTP is such a central piece.

Reference Implementations?

Are there any reference implementations for this API?

Proposal preview: "Universal versioning"

Universal versioning

This is a proposal for expanding the discussion of versioning to include a description of "universal versioning" and encourage its adoption.

⚠️ This is the first time I've transcribed this concept, so hopefully it makes some semblance of sense. I plan to revise this proposal based on comments received for clarity and completeness, and eventually close this issue and create a new one with what I would consider to be a more "final draft" type of proposal.

Changes in API versions can be problematic for existing applications. In particular, small businesses who use external contractors to develop applications that interact with web services can be left without a critical piece of functionality after elimination of a deprecated API, even if the service provider continues to offer the underlying functionality under a different name. To avoid unnecessary problems in this space, service authors are encourages to follow a universal versioning practice, which minimizes or eliminates the need to change API versions over time.

Universal versioning involves defining the behavior of new API calls for all preceding versions of a service, even in cases where early versions of a service did not support the call.

Basic characteristics

APIs using universal versioning use a single (fixed) API version for an extended period of time.

The primary impact to consumers of a universal API is existing applications which strictly utilize API behaviors which were documented at the time the application was created will continue to work for an indefinite period of time.

Expanding an API

Expanding an API after the initial release of a service involves two primary steps.

1. Define the behavior of the new API in the new version¹ of the service.
2. Define the behavior of the new API when invoked in any prior version of the service. This typically involves documenting a specific failure (e.g. 501 as described below), as the distinguishing characteristic(s)² of the new API are not understood by the old version of the service.

By providing both of these definitions, the definition of the new API is constructed in a manner that all versions of the service implement the API in a supported form.

¹ In this context, the "new version" does not actually result in an increase of the major or minor version number used in the URI.
² Should we define distinguishing characteristics in the context of an API? If so, we could define it such that distinguishing characteristics should lie within the reserved API space (next section) to make it easier to define the behavior of new APIs.

Reserved API space

Supporting expansions to an API under a universal versioning approach requires the first version of a universal API to reserve portions of the API space for future expansion. The API space includes several specific items:

• URIs (path and query parameters)
• Request bodies
• HTTP method and headers

Reserved URI for future resources

For any resource resource-name which is not defined by the public API, all HTTP requests to a path starting with the following must return a 501. In addition, a 501 must be returned if the trailing slash is omitted but the resource name is otherwise unchanged.

https://api.contoso.com/v1.0/resource-name/

Unexpected query parameters

The behavior of an HTTP API in the presence of an unrecognized but reserved query parameter, HTTP header, or property of the request body is implementation defined. If the API rejects the call due to the inclusion of an unrecognized reserved element, the return code should be 501.

Deprecation

One of the primary concerns regarding universal versioning is the intentional lack of support for deprecating and eventually removing a supported API call. In general, this design principle increases consumer confidence when developing against an API. However, the identification of certain fundamental performance or security concerns baked into an API may require developers limit or prevent the use of the call at any time.

Deprecation via rate limiting

In cases where performance or security concerns require eliminating support for a prior API, the existing behavior used for reporting failures due to rate limiting may be used to report the API is no longer in service.

Suggested upgrades

The return value used for rate limiting in a universal API should include a provision for notifying callers in cases where an alternate API may be available. When rate limits are reduced (potentially to 0) as a result of a performance or security concern, this provision should be utilized to inform the caller of the change.

Clarification on $top / $skip

I wanted to ask about the meaning of this note:

Note: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options. This will avoid the risk of the client making assumptions about the data returned.

Does this mean if a client asks for the top 5 items and there's only 4, that the API should error instead of returning the 4 items?

As a caller who doesn't know the number of items in a collection, I may want to receive at most 20 items, but I don't want the call to completely fail if there weren't 20 items available.

Producing an error when going out of bounds on skip isn't unreasonable. But from the caller's perspective, having the server return an empty array when you've skipped out of bounds is typically the most natural result to deal with (it doesn't require any extra code to handle the edge case).

I'm not sure which assumptions we're trying to guard the callers against making. If the response doesn't include a @nextLink, they're getting everything that's available that meets the request. If it does include a @nextLink, there's more.

Naming guidelines are needed

The document is missing detailed guidelines on how to name resources, types in metadata documents, headers etc.

References to RFC2616 should probably be switched to RFC 7231 or RFC 7230

RFC 2616 was been replaced by RFC 7230,7231,7232,7233,7334 and 7235 two years ago and is a more consistent, accurate and clearer description of HTTP. Most of the core semantics of HTTP are described in 7231 and would be a better reference than pointing to RFC 2616

Example Reference Implementations

I'm interested in seeing a working example or reference implementation following these guidelines. A code sample tells a 1000 words. As these guidelines are supposed to be generic perhaps a code sample could be written in a few different popular languages.

Personally, I'm interested in seeing a working sample written in ASP.NET Core. There is no OData support in ASP.NET Core, so I'm particularly interested in a generic solution for sorting, filtering, searching, including/excluding properties.

Feedback on Dates and Times in Section 11

Please review the following constructive criticism with regard to the date and time guidelines in section 11.

Iso8601Literal is poorly defined

• ECMAScript is not the normative reference for ISO8601, and actually gets parts of it wrong. For details, refer to my blog on this subject, and to tc39/ecma262#87 and tc39/ecma262#138.
• The preferred reference should be RFC 3339. The W3C's Date and Time Formats note is also applicable.
• The guidance misses a very important consideration, which is that date-time forms should be fully qualified with either Z or a numeric offset +/-HH:MM so that they represent a distinct point in time:
  • "2016-07-16T08:23:45Z" is a specific point in Coordinated Universal Time (UTC).
  • "2016-07-16T01:23:45-07:00" is the same point in time with a particular time zone offset.
  • "2016-07-16T01:23:45" is not a specific point in time. It could be interpreted differently depending on time zones. While this is type of data may be useful within an application, it has very little meaning in an API and should generally be discouraged as an interchange format.
• The guidance misses another very important consideration, which is that date-only forms should not carry any time element or time zone offset.
  • "2016-07-16" is a valid date. Date-only values should always be passed like this.
  • "2016-07-16T00:00:00Z" is not a date. It's a date-time at midnight UTC. The equivalent date value may be quite different when adjusted to the local time zone. This is a commonly encountered anti-pattern, and should be actively discouraged.
  • "2016-07-16T00:00:00" is also not a date. It's a date-time at midnight local time. The main problem here is that not every local date has a midnight (due to daylight saving time spring-forward gaps). For example, "2016-10-16T00:00:00" does not exist in most of Brazil. Given this value, and this time zone context, some implementations may skip forward to 1:00, some may skip backward to 23:00 the prior day, and some may throw an exception.

To address all of these, the guidance should recommend using the date-time and full-date formats defined in RFC 3339 § 5.6.

StructuredDateLiteral is not good advice

• The list of DateKind value codes appears to be invented here. I know of no JSON library that will create or read value in this split two-state form. You would have to create your own intermediate objects, then either have a long case-statement to handle all the different kinds, or limit yourself to one particular kind. Indeed, the guidance talks about how different clients would need to understand the kind of the server. This requirement defeats the purpose of having an interchange format to begin with. In other words, it's no more helpful to have a kind property that tells you what format to expect in the value property than it would be to describe the custom format in the API's documentation.
• The list is by no means complete of all the different custom formats that have been used for date and time values. As soon as you start picking and choosing from which custom formats you want to honor, you open it up for others to add more. Notably absent is RFC822/2822 such as used in HTTP headers, and also the abhorant but widespread ASP.NET JSON date format. (See Scott Hanselman's blog post, On the nightmare that is JSON Dates. Plus, JSON.NET and ASP.NET Web API.) I'm not advocating for either of these, but if you continue down this route - eventually someone will. There are many others also.
• Some of the formats in the list are completely inappropriate for the web.
  • The "O" format is being used for OLE Automation Dates - this format uses an ambiguous local time scale, while most of the others use UTC. Also, some implementations base it from 1900-01-01 or 1899-12-31, instead of 1899-12-30, and there is extra work to account for negative values. This is something that should be only handled directly when interfacing to/from OLE values - such as by calling DateTime.FromOADate or DateTime.ToOADate in .NET. The OADate values themselves should never be put into a web API.
  • The "X" format honors the Excel 1900 leap year bug - really? This should never leak out of Excel. Putting it in an API would be a horrible thing to do.
• This document is supposed to be about best practices - guidelines that REST APIs should follow. Therefore, I highly recommend you remove this section entirely. Formats that are specific to a particular language should not be used in a language-neutral setting. The only advice should be to use the common interchange formats described by ISO8601.

Misc other items

• The info on Durations in 11.4 is good, but it would also be good to mention that one should be careful to avoid specifying Months or Years unless they actually mean the variable unit of time associated with a calendar month or a calendar year. In other words, do not assume all months are 30 days, or all years are 365 days.
• The info on Intervals in 11.5 is acceptable, but it's equally acceptable to simply place each value into a separate JSON property. This is more common in practice, as there are few parsers that natively recognize the interval format. In other words, { "interval" : "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z" } is less commonly used than { "start" : "2007-03-01T13:00:00Z", "end" : "2008-05-11T15:30:00Z" }. Though either are technically acceptable, the latter is usually prefered because it's easier to work with.
  • The same applies for Recurring Intervals in 11.6. Also note that this format is much less commonly encountered in web APIs than it is in scheduling systems. I'm not sure how much value it has in this document as a recommendation for REST APIs.

Thanks.

Feature request: clearer (semantic?) versioning; version tags

Given section 4.2, "Guidelines for existing services and versioning of services"

We do not recommend making a breaking change to a service that pre-dates these guidelines simply for compliance sake. The service SHOULD try to become compliant at the next version release when compatibility is being broken anyway. When a service adds a new API, that API SHOULD be consistent with the other APIs of the same version. So if a service was written against version 1.0 of the guidelines, new APIs added incrementally to the service SHOULD also follow version 1.0. The service can then upgrade to align with the latest version of the guidelines at the service's next major release.

I expected to find a tag that would allow me to link to the (presumably stable) 2.2 version, but it looks like Guidelines.md was created at version 2.3 and that version 2.3 is still a work in progress. It would be nice if there was a tagged, stable version one could link to.

docs should be one-sentence-per-line

The docs should be reformatted to be one sentence per line.
This makes PRs easier to review.
It also makes edits easier by removing the burden of reflowing existing text.

Question: Proper responds status code from API

Hello,

Our team is debating what status code should the API return when the UI sends a request and the API finds no match (empty response). For example:

An existing user do not have anything in his/her shopping cart. The user id is 1234 and UI makes a call to the API (.../api/getcartitem/1234) to get the cart items for this user. Since the user do not have anything in the shopping cart, what status code should this call returns in the response?

From the JavaScript perspective, I am used to handle 404 as an error and not an empty response. From the API developer perspective, 404 is just a status code and since no items were found with this user id, they are returning 404.

Please let us know how should we understand this and the recommended practice. Thank you!

Question about 8.2 : What is "dynamic canary"

It is mentioned security technique called "dynamic canary" (in section https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#82-service-guidance). I can't find information about it. May someone provide a link with information or explain what is it?

The definition of JSON has changed refer to RFC7159

The definition of JSON has changed.
see RFC7159

1. JSON Grammar

A JSON text is a sequence of tokens. The set of tokens includes six
structural characters, strings, numbers, and three literal names.

A JSON text is a serialized value. Note that certain previous
specifications of JSON constrained a JSON text to be an object or an
array. Implementations that generate only objects or arrays where a
JSON text is called for will be interoperable in the sense that all
implementations will accept these as conforming JSON texts.

  JSON-text = ws value ws

any ideas to adapt to this?

[Question] Long running operations on 200 with a Retry-After VS other standards (e.g. w3.org)

Hi there,

I started following the guidelines for Long running operations on 200 with a Retry-After, however, I quickly found that other frameworks such as jQuery does not support 200 with a Retry-After.

An Article from Mozilla indicates that Retry-After is used with "413 Payload Too Large" and "503 Service Unavailable".
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Also another article states the header can be used with 503 or 3XX: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

I'm not sure which standard / guideline is correct here, but I don't feel very confident with using 200 - unless I am missing something here.

Many thanks,
WhozDougie