Listing all public RESTful APIs in a collective

Use a collective services query to discover API documentation about all public RESTful APIs (services) in the entire collective. The query provides the documentation in list format.

The list contains a summary of each service, such as its name, version, and description, and a list of hosts that currently deploy this service. This list is updated in real time, changing as services are added into or removed from collective members. This list contains services from any collective member, regardless of whether the members are Liberty, Docker and Liberty, LoopBack®, or Docker and LoopBack servers.

The default URL for the collective services query is http://controller_host:controller_http_port/api/collective/registry.

Before you begin

The /api/collective/registry API is in the Liberty API Discovery feature. To query for public services in a collective, you must first add the apiDiscovery-1.0 feature to a collective controller server.xml file and then expose the Swagger 2.0 documentation in Liberty REST endpoints. Complete steps 1 and 2 of the procedure in Discovering REST API documentation on a Liberty server.

Procedure

  1. Point a browser at the http://controller_host:controller_http_port/api/collective/registry URL.

    Replace controller_host and controller_http_port with values for the collective controller.

  2. Optional: Change the URL of the public endpoints with the publicURL attribute in the controller server.xml file.

    You can configure the api portion of the http://controller_host:controller_http_port/api/collective/registry URL with the publicURL attribute in the apiDiscovery element of the server.xml file.

    For example, you can use the publicURL attribute to change the location of your collective RESTful service registry from /api/collective/registry to /services/collective/registry:

    1. Add <apiDiscovery publicURL="/services"/> to the controller server.xml file.
    2. Point a browser at the http://controller_host:controller_http_port/services/collective/registry URL.

    For more information about the publicURL attribute, see Discovering REST API documentation on a Liberty server.

Results

The query provides a list of public services:


{  
   "services":[
      {  
         "service":"/airlines/booking",
         "title":"Booking REST APIs",
         "description":"A microservice exposing booking APIs for various airlines.",
         "version":"1.0.0",
         "hosts":[  
            "vm001:9081",
            "vm002:9082"
         ]
      },
      {  
         "service":"/flight/status",
         "title":"Flight Status REST APIs",
         "description":"A microservice exposing flight status APIs for various airports.",
         "version":"1.0.1",
         "hosts":[  
            "vm003:9085"
         ]
      },
      {  
         "service":"/tourism",
         "title":"Tourism REST APIs",
         "description":"A microservice exposing tourism information for various popular destinations.",
         "version":"2.0.0",
         "hosts":[  
            "vm004:9443"
         ]
      }
   ]
}