Microsoft REST API Guidelines

#1

Post by alpb » Tue, Jul 19, 2016, 4:46 PM UTC

Microsoft REST API Guidelines
github.com

Re: Microsoft REST API Guidelines

#2

Post by danpalmer » Tue, Jul 19, 2016, 5:20 PM UTC

Being that guy again, (and sacrificing my karma) but...

This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically.

While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embrace the full benefits of REST, and develop the technology and conventions/standards for integrating RESTful services.

Edit: for an example of what's possible with 'real' REST, check out this talk: https://vimeo.com/20781278 – better documentation, easy parsing, API optimisation without client changes, discovery, and the API is fully human readable/usable as well.

Re: Microsoft REST API Guidelines

#3

Post by pstuart » Tue, Jul 19, 2016, 5:24 PM UTC

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

Any shining examples you'd care to share?

Re: Microsoft REST API Guidelines

#4

Post by yeukhon » Tue, Jul 19, 2016, 5:25 PM UTC

https://evertpot.com/dropbox-post-api/

This discuss some option for the GET vs POST.

In Kibana, everything is done over GET as get parameters, and I find that extremely annoying and a poor design.

A lot of public APIs also don't honor or have any intentions in supporting or using PATCH. Most APIs I have worked with only use PUT for modification. Anything resembles "creation" is automatically a POST.

Re: Microsoft REST API Guidelines

#5

Post by ihsw » Tue, Jul 19, 2016, 5:25 PM UTC

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

There are degrees of completeness and this expands on the REST standard by a whole lot more.

Frankly I would prefer adhering to this standard.

Re: Microsoft REST API Guidelines

#6

Post by petersellers » Tue, Jul 19, 2016, 5:25 PM UTC

pstuart wrote: post #3

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

Any shining examples you'd care to share?

The JSON API spec is pretty good: http://jsonapi.org/

Re: Microsoft REST API Guidelines

#7

Post by varenc » Tue, Jul 19, 2016, 5:25 PM UTC

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

I'm fine with APIs continuing to be disparate systems if they have a simple, sensible design and have comprehensive documentation. Let's just stop calling them "REST" since they're not as you've pointed out.

Re: Microsoft REST API Guidelines

#8

Post by yeukhon » Tue, Jul 19, 2016, 5:27 PM UTC

pstuart wrote: post #3

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

Any shining examples you'd care to share?

Search for "rest api standard" you will find a bunch.

While I like standard, and I am always an advocate of standard, I also don't agree with standard body's decision on the exact format. This is the challenge. HATEOS is an absolutely great idea, but also painful to implement, making payload larger. One question I ask is "how many kinds of resource links do I need to supply?"

Re: Microsoft REST API Guidelines

#9

Post by rimantas » Tue, Jul 19, 2016, 5:28 PM UTC

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

Not sure about your karma sacrifice, but if someone has doubts:

  > What needs to be done to make the REST architectural style clear on the
  > notion that hypertext is a constraint? In other words, if the engine of
  > application state (and hence the API) is not being driven by hypertext,
  > then it cannot be RESTful and cannot be a REST API. Period. Is there
  > some broken manual somewhere that needs to be fixed?

That's by Roy T. Fielding himself (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...)

So if it is not HATEOAS it is not REST. Alas, I am not aware about any term which can be used for these Richardson maturity model Level 2 services.

Re: Microsoft REST API Guidelines

#10

Post by gregmac » Tue, Jul 19, 2016, 5:28 PM UTC

pstuart wrote: post #3

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

Any shining examples you'd care to share?

Agreed, and specifically:

> APIs will continue to be a disparate system that requires custom code for every integration until we can embrace the full benefits of REST

Have an example of a client that DOESN'T require custom code to use an API?

I think this entire debate is summed up best by:

> There is no magical "smart client" that somehow knows that rel=comments means that the link leads to comments about the current resource and can figure out it should POST there to create a new comment. It has no idea what the hell a "comment" is. [1]

[1] https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/