API Invocation with Swagger and Client Generation with Swagger Editor

APIs created in the Platform are published following the Open API standard. Besides, APIs use Swagger as their framework to create and publish them. Besides, the Control Panel offers tools to consume APIs using the Swagger UI, to test the APIs and, using Swagger Editor, to generate client code in different technologies.

API invocation via Swagger 

Once an API is created, in the list of APIs available to that user, you can see:

By selection  SWAGGER, you can view its main screen, similar to this one:

Here you have several available options. Firstly, choose HTTPS (HTTP / HTTPS) protocol.

In the lower part, you can see all the petitions available for the selected API, along with the id that was assigned in the API definition (In cases there are words {in curly braces}, it means that there are entry parameters beyond the basic ones, and their id is between the curly braces).

There are several options in the query types that have been configured, also shown in this screen: GET, POST, PUT, DELETE.

By accessing one of the queries, you can discriminate 2 different blocks:

-          Parameters: where the parameters, needed to perform the query, are described.

-          Responses: where the possible response code are specified.

You can test the query by clicking on t he button “Try it out”, in the upper right part for each query type. This action allows your to fill in the variable fields in the query with your data. One of this will be common to all the queries: The access token, whose parameter name, String type, is X-OP-APIKey. You can get it from the option My APIs>User Tokens.

The other parameters will depend on how you have defined the query. In this example case, you are also requested a "Site" parameter, string type, referring to the position where you want to filter the query.

Once the data has been correctly inserted, run the query by clicking on the button Execute, and you will get a response series like this one:

Here you can see how the REST calls to the platform have been made, along with the responses, in JSON format, that these queries produced.

In this specific example, you can see how it returned all the data that apply to our query's conditions.

API invocation via Postman using OAuth2 token

Same as you used swagger in the previous example, you can use other, different clients -in this case, Postman- thus showing that we can perform the queries using the Bearer Token.

To do this, you need the OAuth2 token. You can get it entering the APIs section, in the platform main page's upper right part:

Once you have it, keep it and generate a new GET type request in the Postman interface, which will invoke our API url to be tested:

Add then the needed parameters with the Params button. It will deploy a form to be filled in, with the previously-defined parameters:

You will also need to include the Authorizations:

And the Headers:

As you can see, Postman has included an Authorization-type header because you configured it in the previous step.

Finally, send the request using the Send button.

In the lower part you can see the request results, being the same we got in the previous step but having used a different-type token:

Platform client generation with Swagger Editor

From the API list you can select

You can also use the Swagger editor, allowing you to generate a client for the selected PAI, in different languages:

In the menu action , select Java.

This downloads a ZIP with the API Java client. You can load this ZIP in your favourite API and configure it to go on your API. To do this:

1. Load the XXX project in  Eclipse
2. Go to the class ApiClient.java and configure the basePath and the Token:

Private final static DefaultApi api = new DefaultApi();

String xSOFIA2APIKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

api.devuelveLosUltimos10Registros(xSOFIA2APIKey);

3. Test the client.