Open API vs. REST API - difference

Question

How is Open API different from a REST API exposed on Internet? When Open API is explained it explains about an API getting exposed in LAN against exposing it to public . So what exactly is the difference?

Answer 1

OpenAPI is documentation for a REST API. Ideally, however, using a REST API should not require out-of-band documentation: the REST API should be self-descriptive and accessible via hypertext.

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

~ Roy Fielding, https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

~ Roy Fielding, https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Answer 2

REST (REpresentational State Transfer) describes a way how a clients and servers interact with each other. REST communication typically bases on HTTP protocol (but that isn't a requirement) and requests are made to a resource URI, possibly containing additional request data, and replies can be anything: HTML, XML, JSON, CSV, plain-text or even raw binary data. It's not a concrete protocol but a way of communication a protocol can use, similar to SOAP or WSDL.

To access a REST service, the client needs to know the REST API that service if offering, so there must be documentation and you need to write code according to that documentation. With OpenAPI this step is automated. With OpenAPI, there exists a machine parse-able file that explains computers how a REST API works. It tells code what requests exists and what replies to expect. To quote from the OpenAPI description:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

https://github.com/OAI/OpenAPI-Specification

So if you have a OpenAPI implementation and an OpenAPI description file of a REST API, you can feed that description file to the OpenAPI implementation and this implementation now knows how to use the REST API, it can generate human readable documentation for you or it could even auto generate code to use the REST API in different languages.

One could compare that to XML and DTD. XML is like REST, just that XML describes data and not communication. But millions of different XML based data formats exist, to parse a XML file correctly, the code needs to know what tags exist, which tags may have which sub-tags, which data to expect as tag content (an int, a string, a UUID, etc.) and so on. All of this is defined by a DTD (Document Type Definition) which is comparable to an OpenAPI description file. Code that understands DTDs can be fed with a DTD and then parse XML data claiming to conform to that DTD and verify if that's actually true (does it only use allowed tags, is the tag interleaving valid, are the tag values correct, and so on).

E.g. here's the DTD for XHMTL:
https://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict