Proposal: Ballerina VSCode try-out plugin for REST APIs

[shafreenAnfar]

Summary

When consuming REST APIs developers usually follow the sequence of introspection, trying-out and then writing the code. Trying-out the code is essential to get some sense about the REST API. This proposal is to develop a VSCode try-out client that is based on Ballerina.

Goals

• Remove the need to learn another technology to try-out a service when working with Ballerina

Motivation

As explained in the summary section, before consuming a REST API, it is quite common to try-out the service to get a look and feel about it. This is usually done using cURL, Swagger tool or VSCode plugin. However, having to learn another technology to try-out a service does not give you the integrated developer experience. Therefore, having a Ballerina VSCode plugin specifically designed for this purpose could eliminate this problem.

Description

The design is inspired by the popular VSCode plugin REST Client. It allows you to send requests to an endpoint and introspect the response. In order to engage the plugin you need to create a file with the extension .http. Then in the file you can type in the request, send it and introspect the response as follows.

Multiple requests can be typed in as follows.

The same thing is mirrored in the Ballerina VSCode try-out plugin with Ballerina syntax. To begin, users need to create the file with the extension .bal.http. Then to send a GET request, users need to do the following.

http:Client|error snowpeak = new ("https://snowpeak-demo.herokuapp.com/snowpeak");
 
###
snowpeak->get("/locations");

First of all, the above code snippet does result in compiler errors, that is why the above code is written in a special file. VSCode try-out plugin should fill in the rest of the code behind the scene. The default targetType is always json. Users can override it if they need.

The above code results in a Send Request action which is similar to the REST Client. Users can click on it to send a request. In return users can see the response as in the REST Client. In addition, unlike in the REST Client, users can see the actual request as well. However, the response must come at the top whereas the request must come at the bottom.

Following is how a POST request is mapped.

snowpeak->post("/reservation",
   {
       "reserveRooms": [
           {
           "id": "r1000",
           "count": 2
           }
       ],
       "startDate": "2022-01-01",
       "endDate": "2022-01-02"
   }
);

The rest of the syntax and functionality stays the same. For instance, multiple request can be separated using ### as follows.

http:Client|error snowpeak = new ("https://snowpeak-demo.herokuapp.com/snowpeak");
 
###
snowpeak->get("/locations");

###
snowpeak->post("/reservation",
   {
       "reserveRooms": [
           {
           "id": "r1000",
           "count": 2
           }
       ],
       "startDate": "2022-01-01",
       "endDate": "2022-01-02"
   }
);

Security

Similar to REST Client, the Ballerina plugin also supports security aspects as well. For instance, if the endpoint is secured using basic authentication, http:Client basic auth feature can be used to authenticate the client.

Validation

Unlike in REST Client the Ballerina VSCode try-out plugin includes validation of URL, headers and the payload. However, this is only possible if the OpenAPI specification (OAS) is next to the aforementioned file. The OAS file should be named as service-desc.yaml. The plugin automatically uses the service description in the file to provide better user experience.

URL

For instance, the URL is validated to see if it is inline with the service description. It could even go further and suggest URL templates for the user to fill in as follows.

snowpeak->get(string `/locations/${"l1000"}/rooms?startDate=${"2022-01-01"}&endDate=${"2022-01-02"}`);

Payload

The same thing can be done with payload as well using the JSON schema definition included in the OAS. When typing in the outbound payload details, the tool should automatically suggest each field along with its documentation. In order to do so it should have a mapping between each URL template and its request payload. The eventual tooling experience should be similar to the experience when using GraphiQL for graphql.

Follow Links

The plugin should be able to interpret href field values as links. Users can click on the links of the response and create sample requests automatically with ### separator. This is useful when REST APIs are written with HATEOAS constraint.