Talk:Overview of RESTful API Description Languages

This article was nominated for deletion on 17 August 2015. The result of the discussion was no consensus.

	This article is within the scope of WikiProject Computing, a collaborative effort to improve the coverage of computers, computing, and information technology on Wikipedia. If you would like to participate, please visit the project page, where you can join the discussion and see a list of open tasks.ComputingWikipedia:WikiProject ComputingTemplate:WikiProject ComputingComputing articles
Low	This article has been rated as Low-importance on the project's importance scale.
	This article is supported by WikiProject Software (assessed as Mid-importance).

Internet Low‑importance

	Internet portal This article is within the scope of WikiProject Internet, a collaborative effort to improve the coverage of the Internet on Wikipedia. If you would like to participate, please visit the project page, where you can join the discussion and see a list of open tasks.InternetWikipedia:WikiProject InternetTemplate:WikiProject InternetInternet articles
Low	This article has been rated as Low-importance on the project's importance scale.

RESTful API Description Language?

Should the title of this article be RESTful API Description Language? Hugh (talk) 06:34, 11 September 2015 (UTC)[reply]

No, because there's no such thing. Especially not as a proper noun phrase, thus capitalised.

The problem is that these are a subset of IDL (Interface Description Languages), a notable term that should be capitalised. Yet this subset has no objective definition by objective sources. Andy Dingley (talk) 08:43, 11 September 2015 (UTC)[reply]

Ok, how about RESTful API description language? Hugh (talk) 15:31, 11 September 2015 (UTC)[reply]

How do the sources that define this notable set of languages refer to them? Or are there any such sources? Andy Dingley (talk) 16:05, 11 September 2015 (UTC)[reply]

HATEOAS is the key pillar of a RESTful API, not an "alternative"

"An alternative approach to building RESTful APIs is known under the acronym HATEOAS..."

Alternative? A world of no, it is key:

The definitive source:

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2

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

Yes, I know when people use the term "REST API" in colloquial conversation they often ignore this, c'est la vie, but in an article that purports to define things, the definitions should be try to be correct, and not purposefully misleading....

I'm not suggesting that we change the name of the article, but I am suggesting that, if we're going to have a section on HATEOAS, we point out that this is an area where theory and reality often contradict, that "RESTful" IDL's often go against the original spirit of REST (but not necessarily), and not stoop to misdirection and spin. — Preceding unsigned comment added by 173.241.250.232 (talk) 18:01, 18 October 2016 (UTC)[reply]

It is not a contradiction betwen theory and reality. If an API doesn't use resource reprensentations containing state transfer links, then it's not REpresentational State Transfer (REST). Calling anything REST or RESTful when there's not HATEOAS is just a wrong use of the terms, however common that misuse is. Nowhere man (talk) 13:47, 7 February 2023 (UTC)[reply]

Article needs cleanup or deletion

As noted by Andy Dingley, this article suffers from WP:LISTCRUFT, and in general, is poorly written.

As an example, § List of Restful API DLs would be better written as tabular data instead of list data, and I'm fairly certain that TvojaStara attempted to link his own repository in an edit to this article on 4 November 2015 (which, as an aside, points to a stale/inactive repository that hasn't been updated since 2017, and the site linked there doesn't even have a domain name record in any DNS server I've looked up). Echohawkdown (talk) 07:13, 1 January 2022 (UTC)[reply]

Removed non-REST IDLs

As the article is about REST, I removed the IDLs I know cannot represent state transfer links.

I'm almost certain Google Endpoints cannot represent REST APIs.
The WSDL spec references REST but has examples of pre-known URLs and zero example of state transfer links.

On the other hand, OData is very explicit about HATEOAS. Nowhere man (talk) 21:20, 7 February 2023 (UTC)[reply]

OpenAPI

Shouldn't OpenAPI (formerly known as Swagger) also be included in this list? Amos Groß (talk) 11:40, 17 March 2023 (UTC)[reply]

The OpenAPI specification makes zero mention of REST or RESTful APIs because it cannot describe a REST API. They discussed it on Swagger's blog: "There are still places that OAS 3.0 doesn’t fully cater to a HATEOS based architecture, which is expected since it wasn’t built to solve those problems." Nowhere man (talk) 01:44, 21 March 2023 (UTC)[reply]