¶ Setting up API Provider
The first step when using RESTwithUS is setting up a Provider. One provider is basically an API service you are connecting to – and this API service can have multiple endpoints or operations. This provider usually has:
- One base URL used with every endpoint (e.g. for Google Calendar API the base URL is https://www.googleapis.com/calendar/v3)
- One authentication method for all API endpoints
For example, if you are planning to connect to the Google Calendar and Youtube services, you need to create two providers (each service has a different base URL). But if you just want to connect to Events and Calendars from Google Calendar API, you need only one provider with multiple API operations.
Tip: We recommend using Postman when connecting to a new API service. If you can connect to an API with Postman, you will be able to easily recreate the settings in RESTwithUS.
If you are creating your own AL extension that should implement connection with some API provider, the recommended way to start is to add your provider to Provider ID RWU enum:
enumextension 50000 "Test Provider ID RWU" extends "Provider ID RWU"
{
value(50000; "TestProvider")
{
Caption = 'Test Provider';
}
}
Tip: You can skip this step for testing purposes and call your operations with provider description instead of enum ID. However, this is not recommended for production applications.
To create a Provider in RESTwithUS, open the API Providers page and select New from menu:
You need to fill in:
- Description – Unique provider description. (For testing purposes you can use this description when calling this provider’s operations from code.)
- Provider ID – Unique provider ID used for calling this provider's operations from code. (Leave blank, if you want to call the operations by description.)
- URL – Base provider URL (e.g. https://www.googleapis.com/calendar/v3 for Google Calendar API)
¶ Authentication
The next step is to set up an authentication for the provider. Since all provider operations usually share the same authentication process, this is done on a provider level. RESTwithUS is supporting following methods of authentication and they are described in separate guidelines:
¶ Provider Headers
Some API operations require sending specific HTTP headers (see example from Postman below) – and sometimes there are headers that are included in each provider request.
Typical example is API key authentication where you are sending the same API key in the header of each request. Another typical example might be required Content-Type header.
You can set these headers for each operation – but if there are headers that apply for the whole provider, it is better to set them on a provider level.
To set provider headers select your API provider from the list and open Related / Headers:
Now fill in the headers and their values:
Tip: If you are sending sensitive information like API key in headers, consider using Variables.
¶ Provider Variables
If there is a value that is used in every provider operation (or is just used repeatedly) – and it is prone to change in the future – the best way is to store it in provider variables. Typical example are API keys: they are the same for every provider operation, you may need to change them in the future, plus it is a sensitive information.
As an added value consider, that you will be storing the value in one place – so if there comes the time to change an API key, you just need to change it in one place and you're done.
To set provider variables select your API provider from the list and open Related / Variables:
Now enter all provider variables and their values:
- If some of the variables contain sensitive information like API keys or passwords, you can check Hide Value option. Such variable value won’t be plainly visible in the page, plus it gets encrypted when exporting whole provider settings.
- For environment specific variables like API keys or password consider checking Do not Overwrite Value checkbox. These variables won't be transfered in .rwu provider package and must be set in a target environment.
To get the variable value, use syntax:
{{!VariableName}}(e.g.{{!ApiKey}}) for a required variable. If any required variable in a request is empty, the operation will end up with error.{{VariableName}}(e.g.{{ApiKey}}) for an optional variable. Optional variables are just deleted from the operation, if they have no value.
You can use variables almost everywhere:
- Provider and operation URL and URL parameters
- Provider and operation headers
- Operation JSON request and response definition
- User Name and Password for Basic authentication
Tip: You can set the variable value from code, too. For more details about variables see guideline Using RESTwithUS variables.
¶ Provider Details
There are some additional information and settings that you can set on a provider level. To access these settings, select your API provider from the list and open Details:
¶ Log
If you want to log every request and response, you can set it up in the Log tab. Each operation call result will then be saved based on the settings (see Debugging, Log and Error Handling):
Tip: For debugging purposes or when connecting to a new API service, using RESTwithUS Batch Entries is a better option than simple logfile.
¶ Field Formats
In some cases you may need to adjust provider formats – i.e. tell RESTwithUS, how this API provider formats some field types. Usually the JSON fields are pretty standard, but for example if your API service returns dates in some not-so-standard format, you can adapt to it using provider details:
