APIs.json treats the aid of the collection and of each API as a stable identity. Without baseUrl those identifiers are built from the host each client used, so two crawlers that reach the gateway under different names index two different collections. Set baseUrl when the document is meant for crawlers or registries.
An API described by an OpenAPI document is listed with the title, description and version from that document, plus links to the document itself and to its Swagger UI. A SOAP proxy is listed with a link to the WSDL the gateway publishes. Any other proxy is listed with its own name and URL. Internal proxies and proxies whose initialisation failed are left out. The tags of the listed APIs become the tags of the collection.
Answers every request that reaches it and ends the flow, so give it an api of its own. RFC 9727 reserves /.well-known/api-catalog for its own format, so that path is refused here.
apisJson:
[ baseUrl: <url> ]
[ tags:
- include | exclude: <tag> ]
[ collectionId: <id> ]
[ name: <name> ]
[ description: <text> ]
[ type: index | collection | blueprint ]
[ kind: <kind> ]
[ created: <yyyy-mm-dd> ]
[ modified: <yyyy-mm-dd> ]
[ maintainers:
- [ name: <name> ]
[ email: <email> ]
[ url: <url> ] ]
Example Configuration
api:
port: 2000
path:
uri: /apis.json
flow:
- apisJson:
baseUrl: https://api.example.com
collectionId: gateway
name: Example APIs
maintainers:
- name: API Team
url: https://example.com/api-team
api:
port: 2000
path:
uri: /apis.json
flow:
- apisJson:
baseUrl: https://api.example.com
collectionId: gateway
name: Example APIs
maintainers:
- name: API Team
url: https://example.com/api-team
Syntax
apisJson:
baseUrl: <string>
collectionId: <string>
created: <string>
description: <string>
kind: <string>
maintainers:
- <contact>
modified: <string>
name: <string>
tags:
- <tags>
type: index
apisJson:
baseUrl: <string>
collectionId: <string>
created: <string>
description: <string>
kind: <string>
maintainers:
- <contact>
modified: <string>
name: <string>
tags:
- <tags>
type: index
Attributes
| Name | Required | Default | Description | Examples |
|---|---|---|---|---|
| baseUrl | false | derived from the Host header of the request | Absolute URL clients reach the gateway under, such as https://api.example.com. It is the origin of the catalog URL and of every api bound to all hosts, and in APIs.json its host is the domain of every identifier. Without it, all of that comes from the Host header of each request, which is correct unless a reverse proxy in front of the gateway changes the origin. An api bound to one host keeps that host either way. | https://api.example.com |
| collectionId | false | apis | Identifier of the collection itself, forming the second half of its <domain>:<collectionId> identifier. | gateway |
| created | false | the day the configuration was loaded | Day the collection was created, as an ISO date. APIs.json requires the member, so the document always carries it. | 2026-01-15 |
| description | false | APIs served by this gateway | Human readable description of the collection. | Every API of the payments platform |
| kind | false | - | Kind of entity the collection describes, such as company, government, opensource, standard, contract or topic. Without it, the document has no kind. | company |
| modified | false | the day the configuration was loaded | Day the collection last changed, as an ISO date. APIs.json requires the member, so the document always carries it. | 2026-01-15 |
| name | false | APIs | Human readable name of the collection. | Membrane Gateway APIs |
| type | false | - | Type of the collection: index for the description of a single API, collection for several APIs, blueprint for the design of a new API. Without it, the document has no type. | collection |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| contact | 0..* | People or teams maintaining the collection, each with a name, an email address or a web page. |
| tags | 0..* | Selects the apis to publish by their tags. Rules apply in order: the first one that matches a tag of the api decides whether it is listed, and an api no rule matches is left out. Without rules every api is listed. A rule's value is a regular expression that must match a whole tag, so a plain name matches just that tag. |