Multiple API on a Landing Page for the root of a domain name.

[leedahl]

So if you have a domain name, whether on one server or multiple, how do you represent multiple APIs.

There are a couple of ways this might be structure from a domain situation.
You may have for example:
example.com/iot/sensor1
example.com/iot/sensor2
example.com/image_processing1
example.com/image_processing2

or

sensor1.example.com/
sensor2.example.com
image_processing.example.com
image_processing.example.com

The root of the domain of course is example.com so how do we link all these APIs together and support discovery.

[jerstlouis]

@leedahl Here are some ideas:

• If there is a distinct link relation type for each of these different APIs then one top-level OGC API landing page at the root might link to the different ones.
• There might be an OGC API - Records at the root that catalogs all these different APIs
• It might be possible to represent the different sensors as different OGC API collections providing the sensor data and/or through a single Sensor Things APIs, and the different image processing using OGC API - Processes which supports different processes

[fmigneault]

api-catalog Well-Known URI (https://www.iana.org/go/draft-ietf-httpapi-api-catalog-08) seems like the best approach.

This is also being considered by Security DWG to unify how other metadata such as security methods of the relevant API can be identified by machines/clients.

This approach, using the application/linkset+json response (examples: https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-08.html#name-example-api-catalog-documen), offers multiple approaches to return API details whether they are hosted on the same domain, over multiple subdomains, or even across different domains. There is no limitation regarding how the server(s) and their APIs are structured.

The rel: api-catalog link can be returned in the landing page to expose it.
Typically, .well-known/api-catalog is used by default (so it can be found even if not exposed in the landing page links), but it is recommended to provide it. The api-catalog draft also permits other endpoints than the Well-Known URI if desired.

See also:

• New I-D: api-catalog (a well-known URI to help discovery of APIs) #333