Swagger is a special tool that automatically composes the RESTful API document of your application.
Its advantage lies in the fact that it allows you not only to look through all the endpoints of the application, but also immediately test them in action by sending a request and receiving a response.
To access Swagger, you need to press on Preview button in the published application and click on the name of the required publishing plan (Deploy Plan).
In the newly opened window a list of available endpoints and methods associated with these endpoints is shown. Some requests are available only for certain groups of authorized users (see the Middleware of the Auth module for each specific request in the Endpoints section). A Bearer Token is required for requests which are allowed for authorized users only.
You can access the corresponding endpoint directly in Swagger to get this token (Auth section, POST /auth request).
Press Try it out and enter login and password to obtain a token.
Request will be sent on Execute. If it went successfully you will see a token field with the Bearer token value.
The second way to get an authorized user token is that the token can be found in the request body of the deployed application.
- Press F12 in your web-browser to open the developer's tool.
- Send any request in your deployed application (to update tables, for example). User who is sending this request has to be authorized for accessing this endpoint.
- Open Network tab and find the corresponding request.
- Go to Headers tab and find Request Headers section. Bearer token will be presented under Authorization.
Provide Bearer token to Swagger by pressing Authorize and pasting the value you copied in the previous step.
For testing requests select the desired group and the method you want to execute. Press Try it out and fill in the request input parameters. Click Execute to execute the response.
The most expected response, if the request is correctly processed by the server, has the code 200 and shows what the response structure should look like.
401 - the request was not completed successfully because the required authorization token is missing or invalid.
404 - the request was processed successfully, but the requested resource was not found.
422 - incorrect parameters were passed to the input of the request.
500 - an error processing the request by the server.
Raise Custom Error
For custom BPs and related requests, it is possible to create custom error codes with descriptions using the Raise Error block in the BP editor. An example of such process is below:
In this case, if the request to the endpoint associated with the BP above fails, the server will issue a 418 error containing the error text when executing the DB: Create Candidate block. The error code in this example can be any one that the user specifies.
Note: the HTTP 418 I'm a teapot client error response code indicates that the server refuses to brew coffee because it is, permanently, a teapot. A combined coffee/tea pot that is temporarily out of coffee should instead return 503. This error is a reference to Hyper Text Coffee Pot Control Protocol defined in April Fools' jokes in 1998 and 2014.
