New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace REST and RESTful appropriately #29

Closed
wants to merge 2 commits into
base: master
from

Conversation

Projects
None yet
@AlexZeitler

AlexZeitler commented Jul 20, 2016

As Roy T. Fielding suggested on Twitter, I replaced the terms "REST" and "RESTful" with "HTTP" / "HTTP API".
I think the guide is a good idea in general but it doesn't consider all aspects of REST (esp. Hypermedia / HATEOAS) so it should not use that terminology.
If plain HTTP APIs are the design goal (which is ok) they should just be called HTTP APIs.

@msftclas

This comment has been minimized.

Show comment
Hide comment
@msftclas

msftclas Jul 20, 2016

Hi @AlexZeitler, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution!

This seems like a small (but important) contribution, so no Contribution License Agreement is required at this point. Real humans will now evaluate your PR.

TTYL, MSBOT;

msftclas commented Jul 20, 2016

Hi @AlexZeitler, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution!

This seems like a small (but important) contribution, so no Contribution License Agreement is required at this point. Real humans will now evaluate your PR.

TTYL, MSBOT;

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 20, 2016

The document makes no mention of any of the constraints a "RESTful" system would need to abide to. It makes no mention of hypermedia as @AlexZeitler mentions and completely muddies an already misused term to refer to something that has nothing to do with REST. The document itself can be very useful, but please call it what it is, which is your HTTP API guidelines. JSON and pretty URLs aren't what make REST.

hhariri commented Jul 20, 2016

The document makes no mention of any of the constraints a "RESTful" system would need to abide to. It makes no mention of hypermedia as @AlexZeitler mentions and completely muddies an already misused term to refer to something that has nothing to do with REST. The document itself can be very useful, but please call it what it is, which is your HTTP API guidelines. JSON and pretty URLs aren't what make REST.

@mcintyre321

This comment has been minimized.

Show comment
Hide comment
@mcintyre321

mcintyre321 Jul 20, 2016

Yes I also agree, this document seems to be about HTTP APIs not REST.

mcintyre321 commented Jul 20, 2016

Yes I also agree, this document seems to be about HTTP APIs not REST.

@AydinMirMohammadi

This comment has been minimized.

Show comment
Hide comment
@AydinMirMohammadi

AydinMirMohammadi Jul 20, 2016

Yes - I also agree. Please replace REST with HTTP.

AydinMirMohammadi commented Jul 20, 2016

Yes - I also agree. Please replace REST with HTTP.

@forki

This comment has been minimized.

Show comment
Hide comment
@forki

forki commented Jul 20, 2016

omg

@mcintyre321

This comment has been minimized.

Show comment
Hide comment
@mcintyre321

mcintyre321 Jul 20, 2016

@AlexZeitler You should update the PR to modify the readme.md and contributing.md also.

mcintyre321 commented Jul 20, 2016

@AlexZeitler You should update the PR to modify the readme.md and contributing.md also.

@ianbattersby

This comment has been minimized.

Show comment
Hide comment
@ianbattersby

ianbattersby commented Jul 20, 2016

+1

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 20, 2016

Contributor

Yes. REST is a very clear set of constraints: client server, uniform interface, layered system, stateless, cacheable, code on demand and hypermedia.

  • It is not about URIs
  • It is not about dates and timestamps
  • It is not about JSON
  • It is not about objects

This document in its current form is misleading and harmful. It further confuses / muddies the term REST. Beyond that, the usage of the term here adds ZERO value.

Please fix this.

Contributor

glennblock commented Jul 20, 2016

Yes. REST is a very clear set of constraints: client server, uniform interface, layered system, stateless, cacheable, code on demand and hypermedia.

  • It is not about URIs
  • It is not about dates and timestamps
  • It is not about JSON
  • It is not about objects

This document in its current form is misleading and harmful. It further confuses / muddies the term REST. Beyond that, the usage of the term here adds ZERO value.

Please fix this.

@AlexZeitler

This comment has been minimized.

Show comment
Hide comment
@AlexZeitler

AlexZeitler commented Jul 20, 2016

@mcintyre321 done.

@Oceanswave

This comment has been minimized.

Show comment
Hide comment
@Oceanswave

Oceanswave commented Jul 20, 2016

👍

@hpoom

This comment has been minimized.

Show comment
Hide comment
@hpoom

hpoom commented Jul 20, 2016

👍

@sharwell

This comment has been minimized.

Show comment
Hide comment
@sharwell

sharwell Jul 20, 2016

Member

REST is a very clear set of constraints: client server, uniform interface, layered system, stateless, cacheable, code on demand and hypermedia.

I find that in practice (i.e. in the minds of various developers), REST is frequently very clear but rarely consistent. I support the use of "HTTP" over "REST" even in cases where the service is "RESTful" simply because it eliminates some of the retraining burden for all the different but strongly-held views on what REST is/isn't.

Member

sharwell commented Jul 20, 2016

REST is a very clear set of constraints: client server, uniform interface, layered system, stateless, cacheable, code on demand and hypermedia.

I find that in practice (i.e. in the minds of various developers), REST is frequently very clear but rarely consistent. I support the use of "HTTP" over "REST" even in cases where the service is "RESTful" simply because it eliminates some of the retraining burden for all the different but strongly-held views on what REST is/isn't.

@cleemullins

This comment has been minimized.

Show comment
Hide comment
@cleemullins

cleemullins Jul 20, 2016

Member

I'm leaning against this, as I believe most developers mean "CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands" when they say REST.

My preference is to meet the expectations of the majority of API consumers, and I believe "HTTP API" wouldn't be what they expect. Personally, if I read "HTTP API" I'm expecting either SOAP or very RPC style APIs.

I do agree, that the lack of (for example) Hypermedia makes this less than ideal from a "Strict Definition of REST" perspective. That's why we have linked off to more authoritative definitions everywhere we can.

I'm very open to updating the intro to be more in line with what's being said in this thread.

Member

cleemullins commented Jul 20, 2016

I'm leaning against this, as I believe most developers mean "CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands" when they say REST.

My preference is to meet the expectations of the majority of API consumers, and I believe "HTTP API" wouldn't be what they expect. Personally, if I read "HTTP API" I'm expecting either SOAP or very RPC style APIs.

I do agree, that the lack of (for example) Hypermedia makes this less than ideal from a "Strict Definition of REST" perspective. That's why we have linked off to more authoritative definitions everywhere we can.

I'm very open to updating the intro to be more in line with what's being said in this thread.

@forki

This comment has been minimized.

Show comment
Hide comment
@forki

forki Jul 20, 2016

@cleemullins why do we give things names anyway!?

forki commented Jul 20, 2016

@cleemullins why do we give things names anyway!?

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 20, 2016

@cleemullins Everyone has a REST API because an HTTP API doesn't sell from a marketing perspective.

hhariri commented Jul 20, 2016

@cleemullins Everyone has a REST API because an HTTP API doesn't sell from a marketing perspective.

@jeppec

This comment has been minimized.

Show comment
Hide comment
@jeppec

jeppec Jul 20, 2016

@cleemullins I'm think you're right that most developers mean "CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands" when they say REST.
In the document you mention that the guideline should "Adhere as closely as possible to accepted REST/HTTP best practices in the industry at-large". CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands, in my definition, isn't best practice - it's just common practice.

For a guidelines like this I'm not sure aligning with the common practice of most developers will yield a result that brings us much forward.
I support renaming from REST to HTTP to make it clear that the approach isn't Restful/HATEOAS or Level 3 according to the Richardson maturity model - http://martinfowler.com/articles/richardsonMaturityModel.html

jeppec commented Jul 20, 2016

@cleemullins I'm think you're right that most developers mean "CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands" when they say REST.
In the document you mention that the guideline should "Adhere as closely as possible to accepted REST/HTTP best practices in the industry at-large". CRUD API using easy-to-understand URLs, URI segments, and standard HTTP commands, in my definition, isn't best practice - it's just common practice.

For a guidelines like this I'm not sure aligning with the common practice of most developers will yield a result that brings us much forward.
I support renaming from REST to HTTP to make it clear that the approach isn't Restful/HATEOAS or Level 3 according to the Richardson maturity model - http://martinfowler.com/articles/richardsonMaturityModel.html

@johngossman

This comment has been minimized.

Show comment
Hide comment
@johngossman

johngossman Jul 20, 2016

Member

My question for the thread is whether folks believe anything in the body of the guidelines is "wrong" or contradicts building a RESTful service? We point people to REST references and then the document is about the "protocol", hence things like JSON formatting, data formats, etc.

By analogy, back in the day when we had a C++ style guide (which we probably still do), it said "Learn the C++ language, do OO programming, here's those references) then the bulk of the document talked about how to use spaces and tabs and where to put brackets...none of which taught the developers about C++ programming or OO.

If we change the wording to HTTP, we're still going to advise people to write RESTful services (as a SHOULD not a MUST).

Ironically, we wrote the document to try to avoid arguing over the definition of REST.

Member

johngossman commented Jul 20, 2016

My question for the thread is whether folks believe anything in the body of the guidelines is "wrong" or contradicts building a RESTful service? We point people to REST references and then the document is about the "protocol", hence things like JSON formatting, data formats, etc.

By analogy, back in the day when we had a C++ style guide (which we probably still do), it said "Learn the C++ language, do OO programming, here's those references) then the bulk of the document talked about how to use spaces and tabs and where to put brackets...none of which taught the developers about C++ programming or OO.

If we change the wording to HTTP, we're still going to advise people to write RESTful services (as a SHOULD not a MUST).

Ironically, we wrote the document to try to avoid arguing over the definition of REST.

@sharwell

This comment has been minimized.

Show comment
Hide comment
@sharwell

sharwell Jul 20, 2016

Member

Ironically, we wrote the document to try to avoid arguing over the definition of REST.

I had a feeling this was the case.

If we change the wording to HTTP, we're still going to advise people to write RESTful services (as a SHOULD not a MUST).

I recommend a MAY instead of SHOULD, on the premise that service developers should be able to adhere to all of the SHOULD portions in a design guidelines document without substantially impairing the efficiency of the service placed in widespread use. In this case, the use of link relations instead of direct URI construction for API calls introduces a substantial overhead in response sizes, increasing bandwidth requirements for servers and slowing down client operations. Since the benefits these relations provide in terms of discoverability are generally meaningless to the overwhelming population who are just users of applications that communicate over HTTP, services should instead prefer documented and stable URI construction practices for efficiency. The MAY regarding a RESTful service only comes into play for a "developer mode", though clear documentation of the API remains a more powerful tool of discoverability than this developer mode ever could.

Member

sharwell commented Jul 20, 2016

Ironically, we wrote the document to try to avoid arguing over the definition of REST.

I had a feeling this was the case.

If we change the wording to HTTP, we're still going to advise people to write RESTful services (as a SHOULD not a MUST).

I recommend a MAY instead of SHOULD, on the premise that service developers should be able to adhere to all of the SHOULD portions in a design guidelines document without substantially impairing the efficiency of the service placed in widespread use. In this case, the use of link relations instead of direct URI construction for API calls introduces a substantial overhead in response sizes, increasing bandwidth requirements for servers and slowing down client operations. Since the benefits these relations provide in terms of discoverability are generally meaningless to the overwhelming population who are just users of applications that communicate over HTTP, services should instead prefer documented and stable URI construction practices for efficiency. The MAY regarding a RESTful service only comes into play for a "developer mode", though clear documentation of the API remains a more powerful tool of discoverability than this developer mode ever could.

@asbjornu

This comment has been minimized.

Show comment
Hide comment
@asbjornu

asbjornu Jul 20, 2016

@johngossman, If the guidelines have no mention of hypermedia or hypertext as the engine of application state (HATEOAS), it by definition does not describe anything reminiscent of REST. REST stands for Representational State Transfer, which explicitly requires the use of hypermedia. If there's no hypermedia, it's not RESTful.

So while the guidelines don't work contrary to building a RESTful API, they don't really help either.

asbjornu commented Jul 20, 2016

@johngossman, If the guidelines have no mention of hypermedia or hypertext as the engine of application state (HATEOAS), it by definition does not describe anything reminiscent of REST. REST stands for Representational State Transfer, which explicitly requires the use of hypermedia. If there's no hypermedia, it's not RESTful.

So while the guidelines don't work contrary to building a RESTful API, they don't really help either.

@mcintyre321

This comment has been minimized.

Show comment
Hide comment
@mcintyre321

mcintyre321 Jul 20, 2016

Here's a quote from the guy who invented the term REST:

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.

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

mcintyre321 commented Jul 20, 2016

Here's a quote from the guy who invented the term REST:

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.

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

@garethj-msft

This comment has been minimized.

Show comment
Hide comment
@garethj-msft

garethj-msft Jul 21, 2016

Member

My view, frankly, is that the title of the document is an attractor more than it is necessarily accurate in the scholarly sense. I'm supportive of dialing down the use of RESTful and REST within the document where they are technically inaccurate against the original definition of the term per @fielding, perhaps in favor of resource-based api or something (still a bit of a mouthful). However, I'm a huge believer that language is a tool for achieving ends, and at the title/readme level, the best communication service I believe we can bring is to get folks who consider that they are building REST APIs, whether they are or not per definition, to take a look at this work and see if they find value in it. I believe we'll reduce the set of folks who do so if we change the title and readme to remove REST and I feel its worth sacrificing some accuracy against the original definition to avoid that.

Member

garethj-msft commented Jul 21, 2016

My view, frankly, is that the title of the document is an attractor more than it is necessarily accurate in the scholarly sense. I'm supportive of dialing down the use of RESTful and REST within the document where they are technically inaccurate against the original definition of the term per @fielding, perhaps in favor of resource-based api or something (still a bit of a mouthful). However, I'm a huge believer that language is a tool for achieving ends, and at the title/readme level, the best communication service I believe we can bring is to get folks who consider that they are building REST APIs, whether they are or not per definition, to take a look at this work and see if they find value in it. I believe we'll reduce the set of folks who do so if we change the title and readme to remove REST and I feel its worth sacrificing some accuracy against the original definition to avoid that.

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 21, 2016

Contributor

The biggest issue I have is this document is that it leaves the reader who does not understand what REST is thinking that the contents therein are what define a good RESTful service. And that is not true, it is orthogonal. The links to Wikipedia and the REST In Practice book make this even worse.

The majority of the guidelines here have nothing to do with REST. I am not saying they are good or bad, they are just something that the REST constraints do not address. So the word ends up really having no value other than maybe saying it is not SOAP?

For example, "11.2 REST guidelines for dates and times". If I drop the "REST" from that phrase does it have any different meaning? No. Does REST address dates and times, no? In most of the cases where REST is used, barring from the section where the guidelines encourage folks to learn about REST, the term is misused.

+1 on toning down completely the usage of the term REST within the document. Encouraging people to learn about REST, Hypermedia, is great.

Contributor

glennblock commented Jul 21, 2016

The biggest issue I have is this document is that it leaves the reader who does not understand what REST is thinking that the contents therein are what define a good RESTful service. And that is not true, it is orthogonal. The links to Wikipedia and the REST In Practice book make this even worse.

The majority of the guidelines here have nothing to do with REST. I am not saying they are good or bad, they are just something that the REST constraints do not address. So the word ends up really having no value other than maybe saying it is not SOAP?

For example, "11.2 REST guidelines for dates and times". If I drop the "REST" from that phrase does it have any different meaning? No. Does REST address dates and times, no? In most of the cases where REST is used, barring from the section where the guidelines encourage folks to learn about REST, the term is misused.

+1 on toning down completely the usage of the term REST within the document. Encouraging people to learn about REST, Hypermedia, is great.

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 21, 2016

@johngossman In answer to your question, I believe there is something wrong, because the document is misleading. It is leading people to believe that was is described here is how you create a RESTful service.

Given the opportunity you have here, and as you point out, your own intentions to stop having people debate on the term, why not make the suggested corrections and then add a section specifically about RESTful constraints and the consequent benefits of imposing these constraints.
This way those that want to adhere to REST know exactly what they need to do and the benefits it provides. Those that don't, can simply use this document as a standard for HTTP APIs up to the point where you talk about REST.

With Microsoft's standing in the community, you have a great opportunity to make things right and contribute to clearing up the term that is so very often misunderstood.

Please reconsider.

hhariri commented Jul 21, 2016

@johngossman In answer to your question, I believe there is something wrong, because the document is misleading. It is leading people to believe that was is described here is how you create a RESTful service.

Given the opportunity you have here, and as you point out, your own intentions to stop having people debate on the term, why not make the suggested corrections and then add a section specifically about RESTful constraints and the consequent benefits of imposing these constraints.
This way those that want to adhere to REST know exactly what they need to do and the benefits it provides. Those that don't, can simply use this document as a standard for HTTP APIs up to the point where you talk about REST.

With Microsoft's standing in the community, you have a great opportunity to make things right and contribute to clearing up the term that is so very often misunderstood.

Please reconsider.

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 21, 2016

Member

Personally, I think the ship has already sailed on the misuse of the term REST, and there are many players in the industry to be blamed for that, however I fear that if MSFT don't use the term REST here, then many customers who might benefit from some the contained guidance will not use it because "they want to do REST"!. Jon Moore told us in the keynote at Restfest 2011 to give up on policing the REST term and just use Hypermedia API if you want to talk about hypermedia APIs. I think that wisdom is appropriate here.

@johngossman The formal definition of REST versus the popular definition of REST applies very specific rules on how clients and servers can be coupled. There are some things in the guidelines that go against the REST constraints. e.g.

  • Specifically defining the format and shape of an error payload. Using the content-type header to identifier a media type such as the one described in RFC7807 would comply with the REST constraints.
  • Requiring that all services MUST support application/json may not directly contradict a REST constraint, but it does seem to violate the intent of building evolvable systems.
  • Making CORS a MUST is similarly constraining. Many APIs are not designed to be consumed by web browsers.
  • Attempting to standardize URL structures such as https://{serviceRoot}/{collection}/{id} encourages additional coupling between clients and servers leading to difficulty in deploying services and evolving services without breaking clients. This is discussed further in RFC 7320
  • The requirements that APIs MUST include a version identifier in a URL is another example of a guideline that is contrary to the formal REST constraints.

These are just some of the things that I have seen so far that are not consistent with goal of building highly evolvable systems. That doesn't mean they are wrong, or bad guidelines, they just achieve a different set of system effects than those that the REST constraints are aiming for.

It might be worth adding a paragraph, that explains the use of the term, for those who are offended by its liberal application.

Member

darrelmiller commented Jul 21, 2016

Personally, I think the ship has already sailed on the misuse of the term REST, and there are many players in the industry to be blamed for that, however I fear that if MSFT don't use the term REST here, then many customers who might benefit from some the contained guidance will not use it because "they want to do REST"!. Jon Moore told us in the keynote at Restfest 2011 to give up on policing the REST term and just use Hypermedia API if you want to talk about hypermedia APIs. I think that wisdom is appropriate here.

@johngossman The formal definition of REST versus the popular definition of REST applies very specific rules on how clients and servers can be coupled. There are some things in the guidelines that go against the REST constraints. e.g.

  • Specifically defining the format and shape of an error payload. Using the content-type header to identifier a media type such as the one described in RFC7807 would comply with the REST constraints.
  • Requiring that all services MUST support application/json may not directly contradict a REST constraint, but it does seem to violate the intent of building evolvable systems.
  • Making CORS a MUST is similarly constraining. Many APIs are not designed to be consumed by web browsers.
  • Attempting to standardize URL structures such as https://{serviceRoot}/{collection}/{id} encourages additional coupling between clients and servers leading to difficulty in deploying services and evolving services without breaking clients. This is discussed further in RFC 7320
  • The requirements that APIs MUST include a version identifier in a URL is another example of a guideline that is contrary to the formal REST constraints.

These are just some of the things that I have seen so far that are not consistent with goal of building highly evolvable systems. That doesn't mean they are wrong, or bad guidelines, they just achieve a different set of system effects than those that the REST constraints are aiming for.

It might be worth adding a paragraph, that explains the use of the term, for those who are offended by its liberal application.

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 21, 2016

Contributor

I am not against the use of REST as long as its intended use is clarified. When we say REST, we mean HTTP services, etc.

Contributor

glennblock commented Jul 21, 2016

I am not against the use of REST as long as its intended use is clarified. When we say REST, we mean HTTP services, etc.

@cleemullins

This comment has been minimized.

Show comment
Hide comment
@cleemullins

cleemullins Jul 21, 2016

Member

@darrelmiller

Thanks for the detailed feedback. I think some of this is explained in our goals section - which perhaps should be made a bit stronger. For example:

Requiring that all services MUST support application/json may not directly contradict a REST constraint, but it does seem to violate the intent of building evolvable systems.

That's not a REST thing, but rather a practicality of life at Microsoft issue. We have "REST" API's that return JSON, some that return XML, some that return, well, something else. In order to make life practical for our consumers, we as a company decided to just say "JSON!". By putting this into the guidelines, and giving the API review board(s) the power enforce, at least we're not building new API's that are XML first and "maybe have JSON some day". I don' think this speaks to general REST at all, but rather building API's here at Microsoft.

A similar point with our error payloads. We have hundreds of teams building APIs, and each of them did/does return errors in a different way. We understand this makes our APIs difficult to consume so we tried to standardize our error format. Again, this isn't a commentary on REST, rather it's "To build an API at Microsoft, you should return errors this way so that our customers don't have to learn yet another error format".

Member

cleemullins commented Jul 21, 2016

@darrelmiller

Thanks for the detailed feedback. I think some of this is explained in our goals section - which perhaps should be made a bit stronger. For example:

Requiring that all services MUST support application/json may not directly contradict a REST constraint, but it does seem to violate the intent of building evolvable systems.

That's not a REST thing, but rather a practicality of life at Microsoft issue. We have "REST" API's that return JSON, some that return XML, some that return, well, something else. In order to make life practical for our consumers, we as a company decided to just say "JSON!". By putting this into the guidelines, and giving the API review board(s) the power enforce, at least we're not building new API's that are XML first and "maybe have JSON some day". I don' think this speaks to general REST at all, but rather building API's here at Microsoft.

A similar point with our error payloads. We have hundreds of teams building APIs, and each of them did/does return errors in a different way. We understand this makes our APIs difficult to consume so we tried to standardize our error format. Again, this isn't a commentary on REST, rather it's "To build an API at Microsoft, you should return errors this way so that our customers don't have to learn yet another error format".

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 21, 2016

@cleemullins So in essence you yourself are pointing out that this is about building API's at Microsoft and following certain conventions. So why not call it "Microsoft HTTP API's"? As opposed to Microsoft REST API's?

And a follow-up, honest question - do you feel that putting REST in here adds any value beyond the hype that everyone has a REST API? Do you think your consumers would be concerned that there isn't actually an API that is denominated as RESTful? Even if this API actually has nothing to do with RESTful systems?

hhariri commented Jul 21, 2016

@cleemullins So in essence you yourself are pointing out that this is about building API's at Microsoft and following certain conventions. So why not call it "Microsoft HTTP API's"? As opposed to Microsoft REST API's?

And a follow-up, honest question - do you feel that putting REST in here adds any value beyond the hype that everyone has a REST API? Do you think your consumers would be concerned that there isn't actually an API that is denominated as RESTful? Even if this API actually has nothing to do with RESTful systems?

@AlexZeitler

This comment has been minimized.

Show comment
Hide comment
@AlexZeitler

AlexZeitler Jul 21, 2016

@cleemullins btw there's a RFC for how errors can be returned in REST/HTTP APIs: https://tools.ietf.org/html/rfc7807

AlexZeitler commented Jul 21, 2016

@cleemullins btw there's a RFC for how errors can be returned in REST/HTTP APIs: https://tools.ietf.org/html/rfc7807

@cleemullins

This comment has been minimized.

Show comment
Hide comment
@cleemullins

cleemullins Jul 21, 2016

Member

@AlexZeitler Thanks for that RFC Pointer. I hadn't seen it before, and just spent an hour reading it. I've opened up an internal discussion to gauge the mood for migrating off our existing "Standard" to the one specified by the RFC.

Are you aware of any other large API providers snapping to this spec? A success story (or 2 or 3) around the format, and the wins from standardizing on it, would be very helpful.

Member

cleemullins commented Jul 21, 2016

@AlexZeitler Thanks for that RFC Pointer. I hadn't seen it before, and just spent an hour reading it. I've opened up an internal discussion to gauge the mood for migrating off our existing "Standard" to the one specified by the RFC.

Are you aware of any other large API providers snapping to this spec? A success story (or 2 or 3) around the format, and the wins from standardizing on it, would be very helpful.

@cleemullins

This comment has been minimized.

Show comment
Hide comment
@cleemullins

cleemullins Jul 21, 2016

Member

@hhariri Thanks Hadi for your questions. This doc is absolutely about building API's at Microsoft following our internal conventions. We think the conventions we're using internally are useful enough that it was worth publishing so others can hopefully benefit from some of the work. If that message didn't come across, then it's my fault and I'll try to correct it.

This doc is saying, "To better serve the many developers who consume our public facing APIs, we should try to make them more consistent.". This doc is an acknowledgement that if you have 100 teams building APIs, then you get 100 very different APIs. We are trying really hard to improve that, and this doc is one of those efforts.

I'm avoiding the HTTP v REST discussion, as I don't really have anything to add there.

Member

cleemullins commented Jul 21, 2016

@hhariri Thanks Hadi for your questions. This doc is absolutely about building API's at Microsoft following our internal conventions. We think the conventions we're using internally are useful enough that it was worth publishing so others can hopefully benefit from some of the work. If that message didn't come across, then it's my fault and I'll try to correct it.

This doc is saying, "To better serve the many developers who consume our public facing APIs, we should try to make them more consistent.". This doc is an acknowledgement that if you have 100 teams building APIs, then you get 100 very different APIs. We are trying really hard to improve that, and this doc is one of those efforts.

I'm avoiding the HTTP v REST discussion, as I don't really have anything to add there.

@AlexZeitler

This comment has been minimized.

Show comment
Hide comment
@AlexZeitler

AlexZeitler Jul 21, 2016

@cleemullins We're currently using it in a SaaS-Project on Azure but it's not officially available at this time.
Maybe @darrelmiller has further info as he has written the ASP.NET Web API implementation for Problem+JSON: https://github.com/tavis-software/Tavis.Problem

Also maybe @mnot has more infos to share as he as contributed to the RFC.

AlexZeitler commented Jul 21, 2016

@cleemullins We're currently using it in a SaaS-Project on Azure but it's not officially available at this time.
Maybe @darrelmiller has further info as he has written the ASP.NET Web API implementation for Problem+JSON: https://github.com/tavis-software/Tavis.Problem

Also maybe @mnot has more infos to share as he as contributed to the RFC.

@bwatts

This comment has been minimized.

Show comment
Hide comment
@bwatts

bwatts Jul 22, 2016

How about "Web APIs"? It aligns with well-known product nomenclature and avoids the co-opting and dilution of the term REST.

bwatts commented Jul 22, 2016

How about "Web APIs"? It aligns with well-known product nomenclature and avoids the co-opting and dilution of the term REST.

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 22, 2016

@bwatts It also might confuse people with a now obsolete stack. Is there anything wrong with actually using HTTP given that it seems the entire guidelines rest on this protocol?

hhariri commented Jul 22, 2016

@bwatts It also might confuse people with a now obsolete stack. Is there anything wrong with actually using HTTP given that it seems the entire guidelines rest on this protocol?

@bwatts

This comment has been minimized.

Show comment
Hide comment
@bwatts

bwatts Jul 22, 2016

@hhariri not at all, but it doesn't really seem to enthuse anyone either. I'm just looking for something that will have an impact on the authors of this document. The tone of the conversation right now is "yeah, we know it's not right, but meh" and it's unclear what anyone could say to move the needle.

bwatts commented Jul 22, 2016

@hhariri not at all, but it doesn't really seem to enthuse anyone either. I'm just looking for something that will have an impact on the authors of this document. The tone of the conversation right now is "yeah, we know it's not right, but meh" and it's unclear what anyone could say to move the needle.

@hhariri

This comment has been minimized.

Show comment
Hide comment
@hhariri

hhariri Jul 22, 2016

@bwatts I'd actually love to hear from the original authors their thoughts, because if they don't care, then I'm pretty much done here.

hhariri commented Jul 22, 2016

@bwatts I'd actually love to hear from the original authors their thoughts, because if they don't care, then I'm pretty much done here.

@mcintyre321

This comment has been minimized.

Show comment
Hide comment
@mcintyre321

mcintyre321 Jul 22, 2016

If HTTP API is too broad (and unmarketable) a term, perhaps we can coin UNREST, as in "UNREST's not REST" (a la GNU).

It would be great to have Microsoft back such a move as all the grassroots efforts to save the term REST have seemingly failed.

mcintyre321 commented Jul 22, 2016

If HTTP API is too broad (and unmarketable) a term, perhaps we can coin UNREST, as in "UNREST's not REST" (a la GNU).

It would be great to have Microsoft back such a move as all the grassroots efforts to save the term REST have seemingly failed.

@distobj

This comment has been minimized.

Show comment
Hide comment
@distobj

distobj Jul 22, 2016

Or, you know, just add a firm recommendation that hypermedia be used; minimize use of ids that aren't URLs, etc..

distobj commented Jul 22, 2016

Or, you know, just add a firm recommendation that hypermedia be used; minimize use of ids that aren't URLs, etc..

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 22, 2016

Contributor

Or just API. Look around, if you go to Yelp's page it is the Yelp API, GitHub API, Bing API.

People get it....MIcrosoft API.

Contributor

glennblock commented Jul 22, 2016

Or just API. Look around, if you go to Yelp's page it is the Yelp API, GitHub API, Bing API.

People get it....MIcrosoft API.

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 22, 2016

Member

@distobj That's just crazy talk ;-) It would be awesome if we could get there one day, but there are just not enough successful examples to point to (excluding of course the elephant in the room) to convince people that it will work.

Member

darrelmiller commented Jul 22, 2016

@distobj That's just crazy talk ;-) It would be awesome if we could get there one day, but there are just not enough successful examples to point to (excluding of course the elephant in the room) to convince people that it will work.

@johngossman

This comment has been minimized.

Show comment
Hide comment
@johngossman

johngossman Jul 23, 2016

Member

I think @glennblock has the proper answer in #48

Member

johngossman commented Jul 23, 2016

I think @glennblock has the proper answer in #48

@tgschulte

This comment has been minimized.

Show comment
Hide comment
@tgschulte

tgschulte Jul 25, 2016

Maybe just call it "RESTful API" and not "REST API" that seems how most employ an adjective to note that on the spectrum of dogmatic to pragmatic, they are some distance from pure dogmatic implementation.

tgschulte commented Jul 25, 2016

Maybe just call it "RESTful API" and not "REST API" that seems how most employ an adjective to note that on the spectrum of dogmatic to pragmatic, they are some distance from pure dogmatic implementation.

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 25, 2016

Member

@tgschulte Personally I don't think that making a distinction between REST and RESTFul helps the situation. And just an FYI, I personally find it offensive when applying all the REST constraints rigorously is described as "dogmatic". I'm pretty sure that wasn't your intention, and maybe I'm overly sensitive after debating this topic for years :-). I apply the constraints because I know the costs and the benefits of applying them, not because I read somewhere that I must apply them to get official seal of REST.
All application of the constraints described by REST should be done pragmatically, whether you apply only one, or apply all of them.

Member

darrelmiller commented Jul 25, 2016

@tgschulte Personally I don't think that making a distinction between REST and RESTFul helps the situation. And just an FYI, I personally find it offensive when applying all the REST constraints rigorously is described as "dogmatic". I'm pretty sure that wasn't your intention, and maybe I'm overly sensitive after debating this topic for years :-). I apply the constraints because I know the costs and the benefits of applying them, not because I read somewhere that I must apply them to get official seal of REST.
All application of the constraints described by REST should be done pragmatically, whether you apply only one, or apply all of them.

@tgschulte

This comment has been minimized.

Show comment
Hide comment
@tgschulte

tgschulte Jul 25, 2016

@darrelmiller Just to be clear, I didn't mean anything offensive by "dogmatic" and I apologize if I did offend.

We here are wrestling with the way to describe succinctly our API as having REST characteristics while acknowledging some specified REST characteristic is not implemented or implemented differently for reasons of practicality. ATM, "RESTful" is feeling like an economic shorthand for that reality especially in emails/posts/etc. where more elaborate disclaimers seem out of place. I have been watching this thread to see what direction it would go for what we could apply.

tgschulte commented Jul 25, 2016

@darrelmiller Just to be clear, I didn't mean anything offensive by "dogmatic" and I apologize if I did offend.

We here are wrestling with the way to describe succinctly our API as having REST characteristics while acknowledging some specified REST characteristic is not implemented or implemented differently for reasons of practicality. ATM, "RESTful" is feeling like an economic shorthand for that reality especially in emails/posts/etc. where more elaborate disclaimers seem out of place. I have been watching this thread to see what direction it would go for what we could apply.

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 25, 2016

Member

@tgschulte No worries :-)

I agree that it would be ideal if there were a term for the "architectural style" for the REST constraints, minus hypermedia and self-descriptive messages. However, I think "RESTFul" and "REST" are used interchangably in too many places to consider trying to make them distinct, despite the fact a few people have been trying to do that for a number of years. The challenge is that "REST" has the marketing buzz, so any new name that we come up with will be rejected.

Member

darrelmiller commented Jul 25, 2016

@tgschulte No worries :-)

I agree that it would be ideal if there were a term for the "architectural style" for the REST constraints, minus hypermedia and self-descriptive messages. However, I think "RESTFul" and "REST" are used interchangably in too many places to consider trying to make them distinct, despite the fact a few people have been trying to do that for a number of years. The challenge is that "REST" has the marketing buzz, so any new name that we come up with will be rejected.

@mloskot

This comment has been minimized.

Show comment
Hide comment
@mloskot

mloskot Jul 25, 2016

In RAML world, APIs that do not obey all constraints of REST are described as "practically-RESTful", from http://raml.org/about/about-raml

We say "practically RESTful" because, today in the real world, very few APIs today actually obey all constraints of REST

Perhaps similar consensus could be achieve in the guidelines document.

mloskot commented Jul 25, 2016

In RAML world, APIs that do not obey all constraints of REST are described as "practically-RESTful", from http://raml.org/about/about-raml

We say "practically RESTful" because, today in the real world, very few APIs today actually obey all constraints of REST

Perhaps similar consensus could be achieve in the guidelines document.

@distobj

This comment has been minimized.

Show comment
Hide comment
@distobj

distobj Jul 25, 2016

In my many years of implementing Web based systems (including some time consulting at Microsoft) I can count on one hand the number of times it was advantageous to disregard the hypermedia constraint. I seriously doubt that there are practical reasons why this was not included in the guidelines. They are guidelines after all, not canon; put in the recommendation to use it, and leave it up to the individual groups to decide the cost for themselves. If these guidelines continue to RFC 2119 language (ugh), make it a SHOULD if you must (pun intended).

distobj commented Jul 25, 2016

In my many years of implementing Web based systems (including some time consulting at Microsoft) I can count on one hand the number of times it was advantageous to disregard the hypermedia constraint. I seriously doubt that there are practical reasons why this was not included in the guidelines. They are guidelines after all, not canon; put in the recommendation to use it, and leave it up to the individual groups to decide the cost for themselves. If these guidelines continue to RFC 2119 language (ugh), make it a SHOULD if you must (pun intended).

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 25, 2016

Member

@distobj The practicalities are that there are not enough developers who understand how to take advantage of hypermedia. There are not enough people training other developers on how to do it, and there it a significant amount of unlearning that needs to be done before practical benefits can be seen. Oh, and tooling vendors haven't figured out how to automate the production of hypermedia APIs. Also, hypermedia is a long term play with some higher upfront costs. Sadly many people don't build software with those goal.

Member

darrelmiller commented Jul 25, 2016

@distobj The practicalities are that there are not enough developers who understand how to take advantage of hypermedia. There are not enough people training other developers on how to do it, and there it a significant amount of unlearning that needs to be done before practical benefits can be seen. Oh, and tooling vendors haven't figured out how to automate the production of hypermedia APIs. Also, hypermedia is a long term play with some higher upfront costs. Sadly many people don't build software with those goal.

@mcintyre321

This comment has been minimized.

Show comment
Hide comment
@mcintyre321

mcintyre321 Jul 25, 2016

Having a paragraph explaining that this document is for a "Richardson Maturity Model Level 2" API might go some way to striking a balance between correctness and incorrectness and providing a pointer to those interested to learn more.

mcintyre321 commented Jul 25, 2016

Having a paragraph explaining that this document is for a "Richardson Maturity Model Level 2" API might go some way to striking a balance between correctness and incorrectness and providing a pointer to those interested to learn more.

@AlexZeitler

This comment has been minimized.

Show comment
Hide comment
@AlexZeitler

AlexZeitler Jul 25, 2016

I agree that it would be ideal if there were a term for the "architectural style" for the REST constraints, minus hypermedia and self-descriptive messages.

Borrowing from Scrum: RESTBut 😄

AlexZeitler commented Jul 25, 2016

I agree that it would be ideal if there were a term for the "architectural style" for the REST constraints, minus hypermedia and self-descriptive messages.

Borrowing from Scrum: RESTBut 😄

@darrelmiller

This comment has been minimized.

Show comment
Hide comment
@darrelmiller

darrelmiller Jul 25, 2016

Member

@mcintyre321 I'd be more enthused to support that if Leonard hadn't decided his MM was a bad idea. ;-)

Member

darrelmiller commented Jul 25, 2016

@mcintyre321 I'd be more enthused to support that if Leonard hadn't decided his MM was a bad idea. ;-)

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 25, 2016

Contributor

@darrelmiller @mcintyre321 yes exactly. Richardson is distancing himself from RMM, because he never meant in to be a yard stick for RESTfullness.

Contributor

glennblock commented Jul 25, 2016

@darrelmiller @mcintyre321 yes exactly. Richardson is distancing himself from RMM, because he never meant in to be a yard stick for RESTfullness.

@distobj

This comment has been minimized.

Show comment
Hide comment
@distobj

distobj Jul 26, 2016

Talk about setting the bar low, folks. Hypermedia is hardly rocket science, it's just a different way of using already familiar technologies. How about something as simple as "Identifiers SHOULD be URLs"?

distobj commented Jul 26, 2016

Talk about setting the bar low, folks. Hypermedia is hardly rocket science, it's just a different way of using already familiar technologies. How about something as simple as "Identifiers SHOULD be URLs"?

@glennblock

This comment has been minimized.

Show comment
Hide comment
@glennblock

glennblock Jul 26, 2016

Contributor

@darrelmiller a lot of Microsoft's APIs (at least Azure) are based on OData and do incorporate hypermedia. Granted when using OData you are crafting the entry point URL using a known structure for the query, but after that you actually can follow links no?

Contributor

glennblock commented Jul 26, 2016

@darrelmiller a lot of Microsoft's APIs (at least Azure) are based on OData and do incorporate hypermedia. Granted when using OData you are crafting the entry point URL using a known structure for the query, but after that you actually can follow links no?

@akuckartz

This comment has been minimized.

Show comment
Hide comment
@akuckartz

akuckartz Jul 29, 2016

👍 no REST without HATEOAS

akuckartz commented Jul 29, 2016

👍 no REST without HATEOAS

@garethj-msft

This comment has been minimized.

Show comment
Hide comment
@garethj-msft

garethj-msft Nov 23, 2016

Member

I think we've made the modification to tone down that we intend to make, and that we've made it clear that we don't intend to change the overall title, which while factually debatable brings, as @darrelmiller says the largest audience who might benefit from the guidance. if there are any more targeted changes at this point that would help clarify further I'm happy to entertain them.

Member

garethj-msft commented Nov 23, 2016

I think we've made the modification to tone down that we intend to make, and that we've made it clear that we don't intend to change the overall title, which while factually debatable brings, as @darrelmiller says the largest audience who might benefit from the guidance. if there are any more targeted changes at this point that would help clarify further I'm happy to entertain them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment