REST Reference Builder

Description

The REST Reference Builder is used to define endpoints, authentication requirements, and more for querying a third-party REST API.

Discussion

The REST Reference Builder creates an Xbasic class that can be used to make API calls against a third-party REST service in a server-side script. Scripts to query the API are inserted into server-side code using the REST Reference Genie. The genie generates the code required to call the endpoint configured in the REST Reference. Endpoints, or Actions, are made available as methods of the Xbasic class for the REST Reference.

Creating a REST Reference 

To create a REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button. This opens the New Service Type dialog.

In the REST section, click Create a new definition to consume a REST service to create a new REST Reference.

New Service Type dialog
New Service Type dialog

The REST Reference can be created from an existing Google Service, imported from a Swagger definition, or built from scratch.

Enter Name of REST Reference dialog
Enter Name of REST Reference dialog

To create a REST Reference for a Google service, click the Import Google Service... URL and select the desired Google service. Refer to Google's documentation for the desired API for more information about using the selected API.

Google REST Service Definition Import
Google REST Service Definition Import

Some REST APIs provide a Swagger definition. A Swagger definition is a JSON document that describes a RESTful API. If the API that you'd like to use provides a Swagger definition, you can use the the Import Swagger... link to import the Swagger definition. The Swagger definition can be pasted directly into the window, imported from a URL, or loaded from a local file. Alpha Anywhere will use the definition to generate the REST Reference.

Enter Swagger Definition
Enter Swagger Definition

After entering a Name, you can click Create to generate the REST Reference. Alpha Anywhere will create a new file with an "a5restapi" extension with the name specified in the Create REST Reference dialog. The Edit REST Service Definition may also automatically open.

Overview of the Edit REST Service Definition dialog 

The Edit REST Service Definition dialog contains the REST Reference definition. Included in the definition is the REST API URL, endpoints (Actions), Named Resource Providers, and other information required to call the API.

If you don't import a Google service, the Edit REST Service Definition dialog opens after creating the service.

Edit REST Service Definition
Edit REST Service Definition

Properties 

The Properties tab contains the base URL and Provider information for the API:

Property
Description
Resource URL

The base path for the REST service. E.g. https://www.myservice.com/v1/api/

Public Access - Provider

The API endpoint for endpoints that don't require authentication. Public endpoints may require an API key but generally don't require the user to provide credentials, such as OAuth credentials.

Private Access - Provider

The API endpoint for endpoints that require authentication, such as OAuth.

Endpoints for the REST API are added as Actions. An Action specifies the Path, parameters, the method (GET, POST, etc), and the schema for content sent in the body and header of the request.

You can add an Action using the Add Action button. You can also create an Action by importing from a CURL command via Import from CURL....

Import from CURL
Import from CURL

Placeholders can be used where needed in the URL and body using the syntax {placeholder_name}. "placeholder_name" corresponds to the value of Name for a Parameter, defined at the bottom of the dialog using the Add Parameter button. Any headers required by the endpoint are also defined as Parameters.

Edit Action dialog
Edit Action dialog

REST Reference Genie 

The REST Reference Genie generates the Xbasic to call an endpoint defined in a REST Reference. The genie is found in the context menu for the Xbasic editor. Right-click anywhere in the Xbasic editor, then select Genies... > REST Reference call....

REST Reference call option in the context menu
REST Reference call option in the context menu

Select the REST service in the Service column that you'd like to use, then choose the endpoint to call in the Method column. Alpha Anywhere will display the Xbasic to call the endpoint in the code window at the bottom of the dialog. Click Copy Example to Clipboard to copy the code. When you click OK, the code for the selected method is automatically inserted into the Xbasic editor at the cursor location.

Pick a REST Service and Method dialog
Pick a REST Service and Method dialog

The Generate dropdown box at the top fo the dialog can be used to add help information to the Xbasic in the form of comments.

Example: Building a REST Reference using the Random Useless Facts API 

In this example, we'll build a REST Reference for the Random Useless Facts API. The Random Useless Facts API is a free public REST API that returns a random useless fact. The API has two end points: /random, which returns a random useless fact, and /today which returns the useless fact of the day. Facts can be retrieved in German (de) or English (en) in a variety of formats (.html, .json, .txt, or .md). For example, the URL to retrieve a random fact in English as JSON is:

https://uselessfacts.jsph.pl/random.json?language=en
  • Creating the REST Reference 

    To create a new REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button.

  • When the New Service Type dialog appears, select Create a new definition to consume a REST service in the REST portion of the dialog.

    New Service Type dialog
    New Service Type dialog
  • Enter a name for the REST Reference then click Create. In this example, we'll name the REST Reference randomFact.

    Enter Name of REST Reference prompt
    Enter Name of REST Reference prompt
  • After creating the REST Reference, Alpha Anywhere opens the reference for editing. The Edit REST Service Definition builder is where you specify the REST API URL, authentication requirements, and endpoints (Actions) that you'd like to call.

    Edit REST Service Definition builder
    Edit REST Service Definition builder
  • Next, we'll configure the Resource URL for the API. Add the following information to the Edit REST Service Definition builder:

    Resource URL

    https://uselessfacts.jsph.pl

    The Random Useless Fact API does not require authentication, so the Public Access and Private Access properties should be blank.

    Now that we've defined the Resource URL, we can add Actions for the /random and /today endpoints. Click the Add Action button to add a new action.

    Add Action button
    Add Action button
  • The first action we'll add will call the /today endpoint. Enter the following values in for the corresponding property in the Action editor:

    Property
    Value
    Name

    today

    Method

    get

    Access

    public

    Next, we'll define the Path. Click the smart field button for the Path property. Then, enter the following values in the Path and Query Parameters text boxes:

    Property
    Value
    Path

    /today{format}

    Query Parameters

    language={language}

    Defining the Path and Query Parameters
    Defining the Path and Query Parameters
  • The /today endpoint has two optional parameters you can use to request a specific file format and language to use when returning the fact. The file format is part of the path. For example, /today.json will return the fact in JSON format.

    To make the call dynamic, we can specify a placeholder in the path representing the optional format: {format}.

    The language is passed to the endpoint as a query parameter. E.g. /today?language=en returns the fact in English. We can use a placeholder, {language}, in the Query Parameters to make the is a placeholder for the requested language.

    Click OK to save the Path definition.

  • After defining the Path, we next need to define the parameters used in the path definition. We'll configure the {language} placeholder first. Alpha Anywhere should automatically add a parameter for language after saving the Path.

    Specifying parameters
    Specifying parameters
  • If there are no parameters listed in the dialog, you can create the language parameter using Add Parameter: click the Add Parameter button to add a parameter, select the Query option, then click OK.

    Add a new Query Parameter
    Add a new Query Parameter
  • Verify that the Query parameter for language has the following values for Name and Location:

    Property
    Value
    Name

    language

    Location

    Query

  • Next, we'll create the format parameter. Click Add Parameter, select the Path option, then click OK.

    Add a new Path Parameter
    Add a new Path Parameter
  • Select the new path parameter. Then, enter the following values for the Name and Location properties:

    Property
    Value
    Name

    format

    Location

    Path

    The complete definition for the today endpoint
    The complete definition for the today endpoint
  • When you've finished defining the {format} parameter, you can test the Action. Click Test to open the Action tester

    Action test dialog
    Action test dialog
  • Enter a language and format in the language and format. The Random Useless Fact API supports the following values for language and format:

    Language Options
    Description
    en

    Return the fact in English

    de

    Return the fact in German

    Format Options
    Description
    .html

    Return the fact formatted as HTML.

    .json

    Return the fact formatted as JSON.

    .txt

    Return the fact formatted as plain text.

    .md

    Return the fact formatted as Markdown

    The image below shows the result of calling the endpoint with language set to "en" and format set to ".json":

    Action test results
    Action test results
  • When you are done testing the endpoint, click Save to save the Action.

    Repeat the process above to add the /random endpoint. The /random endpoint takes the same optional parameters as /today. The Action definition should be identical to /today with the exception of the path portion for the Path parameter, which is defined as /random{format}.

    After adding the /random Action, save the REST Service Definition. It can now be added to any Xbasic script using the REST Reference Genie.

See Also