Classification of HTTP-based APIs

"This table provides a classification of HTTP-based APIs. The classification achieves an explicit differentiation between the various kinds of uses of HTTP and provides a foundation to analyse and describe the system properties induced. Providing distinct names for the API 'styles' overcomes the useless situation where APIs are named 'RESTful' and 'not so RESTful','almost RESTful', or 'unRESTful'. An API either adheres to REST's interface constraints or it does not and if it does not, there is no sense in referring to 'REST' in the API's name. Especially so because mentioning REST might cause the false impression that the achieved system would share the same system properties as RESTful systems. They do not - and it is important to understand that the system being designed might not have the expected properties. For example, caching and visibility can be ruined by tunneling operations though action names in URIs.

The most important distinction to be made today is the one between the two HTTP-based API kinds HTTP-based Type I and HTTP-based Type II on the one hand and REST on the other hand. The former two, while not RESTful due to their violation of the hypermdia constraint, can be a reasonable design choice if the tight coupling they induce is acceptable for the given system. This might be the case if the expected life time of the system does not warrant the considerable work of designing a proper media type. However, it must be explicitly understood that both API kinds, 'HTTP-based Type I' and 'HTTP-based Type II' lead to systems in which clients and servers are coupled by their original design and that the evolvability properties of RESTful systems are in no way induced."

  • Classification of HTTP-based APIs
KOS Type
  • en
URI http://bartoc.org/en/node/402
Homepage https://web.archive.org/web/20110824015753/http://www.nordsc.com/ext/classification_of_http_based_apis.html
  • en