Roadmap Proposal

Overview

OpenAPI provides a common framework for designers, developers, testers, and devops to build and maintain REST APIs. We aim to generate a specification page that documents the REST endpoints and provides a tool to execute them with appropriate parameters. The consumers can understand and connect with the API remote services using the UI.

This document will specify the integration of REST endpoints that Hasura uses/generates with the OpenAPI specifications and generate json accepted by OpenAPI standards to design, build, document, test and standardize REST API endpoints.

Why integrate OpenAPI?

• Helps in collaborative API development
• OpenAPI definitions can be converted to code using tools like swagger-codegen
• Provides machine-readable definitions, providing easy testing
• Generates interactive documentation integrated with test UI clients

What do we need to generate the swagger specification?

• API endpoint (URL)
• Method of the API (POST/GET)
• Parameters required (query variables in our case)
• Request body (GQL variables)
• Response body (can be generated if we know the query and data types)

How will the user access the openAPI documentation?

• User will go to api/swagger/json
• They will get the swagger specification (JSON/YAML), that may be rendered as the swagger UI (an example)
• The user will be asked to provide some authentication token (can either be x-hasura-admin-secret or JWT) in swagger UI to access the endpoint

What will happen in the HGE?

To tackle this, we will:

Generate the OpenAPI specification when the user hits the endpoint (api/swagger/json). This will dynamically generate the JSON blob based on the current role of the user. We need to create the OpenAPI specification JSON blob using the REST endpoint specification. The REST endpoint specification can be extracted from either the schema cache, schema cache would be a good option for this (precomputing when dependencies change, more information about any issues upfront rather than at query-time).

Following is the roadmap for extracting the OpenAPI specification from the schema cache:

• First, extract the relevant information from the schema cache. The endpoints are stored as triemap in the schema cache, which is a list of endpoints, a typical endpoint data stored in the list is: \

[
    {
        "tag": "PathLiteral",
        "contents": "myAPIpost"
    },
    {
        "_trieData": {
            "POST": [
                {
                    "definition": {
                        "query": "mutation MyMutation($col_1: String = \"\", $col_2: String = \"\", $id: Int = 10) {\n  insert_table_1(objects: {col_1: $col_1, col_2: $col_2, id: $id}) {\n    affected_rows\n  }\n}"
                    },
                    "url": "myAPIpost",
                    "methods": [
                        "POST"
                    ],
                    "name": "newAPI",
                    "comment": null
                }
            ]
        },
        "_trieMap": []
    }
]

• The API endpoint can be extracted from the url field and the allowed method from the methods list, the parameters can be extracted from the query by parsing the GQL query (?) and the response body can also be generated from the GQL query (?).
• Then the JSON blob of the endpoints in OpenAPI specification can be sent to the user (or we can serve the json in a swagger UI as well)

How are we going to serve the swagger UI - Proposal

1. Expose the Swagger JSON directly for the user. We can add a button in the console where user can download the JSON and then they can use Swagger editor of their choice (eg. https://editor.swagger.io/).

2. Serve the Swagger UI at an endpoint (/api/swagger) using a CDN (eg. https://www.jsdelivr.com/package/npm/swagger-ui-dist).

3. Create our own custom Swagger UI using the OpenAPI JSON (refer to https://github.com/swagger-api/swagger-ui).

We can also embed the Swagger UI (editor.swagger.io) in an iFrame

We can serve the static Swagger files without a CDN and use them to render the OpenAPI JSON directly.

An example of serving Swagger UI using CDN (Option 2)

<!DOCTYPE html>
 <html lang='en'>
 <head> 
     <meta charset='UTF-8'> 
     <meta name='viewport' content='width=device-width, initial-scale=1.0'> 
     <meta http-equiv='X-UA-Compatible' content='ie=edge'> 
     <script src='https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui-standalone-preset.js'></script> 
     <script src='https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui-bundle.js'></script> 
     <link rel='stylesheet' href='https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui.css' /> 
     <title>Swagger</title> 
 </head> 
 <body> 
     <div id='swagger-ui'></div> 
     <script> 
         window.onload = function() { 
           SwaggerUIBundle({ 
             url: '/api/swagger/json', 
             dom_id: '#swagger-ui', 
             presets: [ 
               SwaggerUIBundle.presets.apis, 
               SwaggerUIStandalonePreset 
             ], 
             layout: 'StandaloneLayout' 
           }) 
         } 
     </script> 
 </body> 
 </html>

Currently we are simply exposing the JSON as per options 1.

How to generate types from query representation?

The query parser that is being used resolves the query, a subsequent method statically analyzes the type of each field present in the query by leveraging the introspection schema.

Future Work/ Open Ended Questions

• How to handle authentication in openAPI interative UI?
• Should we expose different information based on the role of the user?