Skip to main content

How can we help?

Frequently searched: Android devices, cloning, ADC Gallery, Glossary,...

AskiaField API

In this section, you will find tutorials and examples on how to use the AskiaField REST API, which was introduced with AskiaField 5.4.

In this article

    Connecting to CCA Web API with POSTMAN

    Postman is a REST API client, which allows you to generate queries to web API's, and read responses sent back. It is a convenient tool to play around with APIs before and during the creation of your app.

    Pre-requisites

    Setup the environment

    1. Connect to the CCA platform via Supervisor.
    2. Open CCA settings.
    3. Make sure the CCA settings include the CCA API URL. It is given to you during the installation phase, and looks like this: https://{YOUR_SERVER_ADDRESS}/CcaAPI/CcaAPI.Service.svc cca_api.png

    Authentication to the API

    Creating a permanent token

    There are a couple ways to authenticate to the API. The most common one is setting up a permanent authentication token. This token is generated using a combination of a user name + a module. When using this token, you will only be granted privileges that would be granted to this user, in the context of the module.

    Here is how to setup your permanent token . . .

    1. First, from the Modules view, add a new module.
    2. Set "allow permanent tokens" to "Yes".token1.png
    3. Then, navigate to the Authentication Tokens view and click "Add". 
      token2.png
    4. Put in a description for the token and select the "Agent". Logging in with that token will then be equivalent to logging in with that user's credentials. The user will benefit from the same restrictions, regardless of their authentication method. 
      token3.png
    5. Select the module to which this token will grant access to.
      token4.png
    6. Make sure to set an expiration date if needed. Once this date is expired, access will be revoked.
    7. You can then read and use the token contained in the first column. Write it down (it will look like this example string: A-b189a7c5-804d-403f-ac4a-a940dfsfdfs) . . .
      token5.png
    8. From the "Restriction" panel, make sure that the agent's restriction allows them to use the newly created module.

    Using Postman

    1. Import the following request file into Postman.
    2. Create a new Postman environment (see how from Postman documentation).
      3.png
      1. Give it a friendly name.
      2. Insert the following key/value pairs:
        1. URL / {YOUR_SERVER_ADDRESS} e.g. demo.askia.com.
        2. token / {thetoken_you_just_wrote_down}.
    3. Select the newly created environment.
    4. Select one of the queries from the imported collection called "CCA API".
    5. Hit "send" and check the responses.
      4__1_.png

    WEB API Reference

    The reference documentation is included directly in your CCA instance. You can navigate to http://[your server address] / ccawebapi to browse the various REST keywords.

    Alternatively, here is a public one: http://demo.askia.com/ccawebapi

    Further examples

    An alternative authentication method is by using username + password + module

    It is achievable by sending a . . .

    POST /session

    . . . request, whose body contains the following payload . . .

    {username: "YOUR_CCA_LOGIN", password: "YOUR_CCA_PASSWORD", module: "YOUR_MODULE_NAME"}

    . . . and reading the output token from the response. This token is valid for a specific duration, set in CCA. (By default 1 minute).

    Authorization : Bearer {YOUR_TOKEN}

    Here is an example implementation of a JS wrapper around this API. You can use this in a sandbox environment to play around with examples.

    https://github.com/FlagBenett/askiaFieldJS

    Related articles