3.2. Hello world

3.2.1. Requirements

For this tutorial, you will need:

3.2.2. Create a new account and application

Click on "Accounts" in the menu or navigate to accounts page.

Click on the Plus icon:

Add account

Name new account: "tutorial"

Create tutorial account

You have now created a new top level account:

Tutorial account created

Click on "Applications" in the menu or navigate to applications page.

Click on the Plus icon to create a new application. Assign the application to the "tutorial" account and call it "quick_start".

Create application

You have now created the "quick-start" application that our resource will belong to:

Application created

3.2.3. Configure users and roles

3.2.3.1. Create a developer role for the new application

Click on "User Roles" in the menu or navigate to user roles page.

Click on the plus icon and assign yourself the developer role for Account: tutorial and application: quick_start.

Create developer role

You now have permission to create a resource for the newly created quick_start application.

3.2.3.2. Create a "Hello world!" resource

This resource will display "Hello world!" in the result in whatever format the client requires, and will have security that requires an active token from a user with a developer role. The authentication method will vbe bearer token.

3.2.3.2.1. Define the resource name, description, and URL

Fill out the following fields in the interface:

  • Name: Hello world
  • Description: A quick-start hello world resource
    • This is the description of the resource that appears in resources page.
  • Account: tutorial
    • This assigns the resource to the account tutorial.
  • Application: quick_start
    • This assigns the resource to the application quick_start.
  • Method: GET
    • This declares the HTTP method.
  • URI: hello/world
    • This defines the URI fragment for the request that comes after / //. 8 TTL: 30
    • This gives the resource a cache time of 30 seconds.

Resource definition

So far, we have defined a resource that can be called from (GET) https://api.apiopenstudio.local/tutorial/quick_start/hello/world.

However, it does nothing and has no security yet.

3.2.3.2.2. Define the security

Add the following snippet to the Security section:

processor: validate_token_roles
id: security
roles:
     - Developer

This calls the processor validate_token_roles. We're giving the processor an ID name of "security", so that if there are any bugs we can see where the error is in the result.

The validate_token_roles processor requires 1 input:

  • roles - the roles to validate the requesting user against.

roles will not require processing from another processor, because this does not need to be dynamic. So we're using a static string: "Developer".

3.2.3.2.3. Define the process

Add the following snippet to the Process section:

processor: var_str
id: process
value: 'Hello world!'

This will use a single processor: var_str. This processor returns the value of a strictly typed string.

It's input value does not need to be dynamic here, so we're giving it a static string value.

Resource process

3.2.3.2.4. Save

Click on the Upload button.

The resource will be parsed and checked for any error, and saved to the database.

If you navigate back to resources page, you should see your new resource.

Resource created

If you click on the download button in the listing for Hello world and select YAML format, it should look like this:

name: 'Hello world'
description: 'A quick-start hello world resource'
uri: hello/world
method: get
appid: 2
ttl: ''
security:
    processor: validate_token_role
    id: security
    roles:
        - Developer
process:
    processor: var_str
    id: process
    value: 'Hello world'

You can edit and upload this yaml file as you wish.

3.2.3.3. Run the new resource

Open up your REST client

3.2.3.3.1. Get a new token for your user

  • Method: POST
  • URL: https://api.apiopenstudio.local/apiopenstudio/core/login
  • Header:
    • Accept: application/json
  • Body:
    • x-www-form-urlencoded
    • fields:
      • username:
      • password:

User login request header

User login request body

The result should be something similar to:

{
    "token": "13ae430eb19a6651378e22e3a37de8cf",
    "uid": 2
}

Copy the value for the token.

3.2.3.3.2. Run Hello world!

  • Method: GET
  • URL: https://api.apiopenstudio.local/tutorial/quick_start/hello/world
  • Header:
    • Accept: application/json
    • Authorization: Bearer

The result should be something similar to:

"Hello world!"

Hello world result

If we change the Accept value in the header to application/xml, we will get something similar to:

<?xml version="1.0"?>
<apiopenstudioWrapper>Hello world!</apiopenstudioWrapper>

3.2.4. Exercises

  1. Fetch a get variable and assign this to the var_str.
  2. Set up a var in the admin interface, hello_world_string: "Hello world!"
    1. adapt the process section so that it fetches the var hello_world_string and assigns the value to the var_str.