Definitions

An API corresponds to an [OpenAPI specification] (OAS) file

There are multiple ways to define the term API. In Benify APIs, we will use the term as a collection of callable URL’s defined together in a single [OAS] file, i.e., “an API” will be roughly equal to an [OAS] file containing definitions of one or more callable URL’s, also called paths. Methods can be called for on a path resulting in operations being performed. A Method is one of a predefined set of HTTP methods: GET, PUT, POST, PATCH, DELETE, INFO, HEAD, …

Path

The term path has different meanings in different standards. In [OAS], a path is the same as a path in this document. In [RFC9110], a path is kind of defined as a number of path elements separated by the character “/”. We chose to mimic the [OAS] definition of path since we are standardizing on using [OAS] to define the services our API offers.

RestFUL – ish…

RestFUL-ish… is not really REST (for a definition of REST see [fielding_dissertation] or, for a more “popular” version, [Wikipedia_REST], but it is close enough to be useful without bringing the “extra burden” of links.

Pre-view APIs

APIs are versioned according to [SemVer]. Major version “0” is a special case: “Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable” (from [SemVer spec-item-4]). Therefore, “v0” APIs are “pre-view APIs”.