Proposal: BLEST Introspection via Utility Routes

Introduction

Introspection allows developers to query an API to learn about its available endpoints, data structures, and supported operations regardless of whether they have access to its source code. Introspection is particularly helpful for exploring third-party APIs and enabling IntelliSense in IDEs. Here we outline a proposal for API introspection within the BLEST protocol.

Approach

It is important that every interaction with the API (including introspection) conforms to the BLEST request format. This is not only for the sake of simplicity, but also to support the goal of being protocol agnostic (i.e. not just HTTP). While BLEST requires all API routes to begin with a letter, this proposal introduces the concept of underscore-prefixed server "utility routes". Two examples of this would be one to list all available routes and another to get specific information about a route. Below is an example of a BLEST request to the "_list" and "_route" utility routes.

Demonstration

"_list"

The "_list" request would ask for a list of all available routes. The "_list" response would contain an array called "routes" with all the discoverable routes of the API.

Request

[
  [
    "18198f4e-aa88-4c82-bf3d-dc56dcf72212",
    "_list"
  ]
]

Response

[
  [
    "18198f4e-aa88-4c82-bf3d-dc56dcf72212",
    "_list",
    {
      "routes": [
        "listProducts",
        "getProductById",
        "addProductToCart",
        ...
      ]
    }
  ]
]

"_info"

The "_info" request would ask for information on a specific route. The "_info" response would contain a description of the route and optional JSON schemas of its parameters and result objects.

Request

[
  [
    "334a84c7-b789-4cdd-9864-197f56beb603",
    "_info",
    {
      "route": "getProductById"
    }
  ]
]

Response

[
  [
    "334a84c7-b789-4cdd-9864-197f56beb603",
    "_info",
    {
      "route": "getProductById",
      "description": "Look up a product by its ID",
      "parameters": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string"
          }
        },
        "required": ["productId"]
      },
      "result": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string"
          },
          "productName": {
            "type": "string"
          },
          "category": {
            "type": "object",
            "properties": {
              "categoryId": {
                "type": "string"
              },
              "categoryName": {
                "type": "string"
              }
            }
          },
          ...
        }
      }
    }
  ]
]

Requirements

The underscore prefix must be reserved for BLEST utility routes.
All implementations of BLEST utility routes must adhere to officially published specifications.
Enabling introspection, defining parameter and/or result schemas, and specifying the discoverability of specific routes must be left to the API developer's discretion.

Conclusion

At the time of writing this is just a proposal. Utility routes and API introspection have not been added to the reference implementations, nor are they in the immediate roadmap. This proposal should serve as guidance for library and framework developers wanting to implement BLEST introspection as well as a conversation starter for brainstorming other use cases for utility routes.

Next Step: Try BLEST for yourself