Service API

Introduction

The Atmo FluD service provides an API that can be used by another service in an automated manner, without user intervention. A user (Alice) can sign-on in another service, e.g. the “api-caller” service. Then the api-caller service can access the API of atmo-flud on behalf of Alice.

Requirements

A service that uses the Atmo-FluD’s API should be assigned with the role atmo-flud: api in the NEANIAS AAI. Any request to the API should contain:

  • The authentication token of the service

  • The authentication token of the user

Atmo-FluD replies to the API calls after validating the authentication tokens and the assigned roles of service & user.

All response bodies are JSON encoded. A single resource is represented as a JSON object. A collection of resources is represented as a JSON array of objects.

Endpoints


GET /api/files/service

Get all input files provided by the service, along with their size in bytes.

Example HTTP request:

GET /api/files/service HTTP/1.1
Host: atmo-flud.neanias.eu
Authorization: Bearer <SERVICE-TOKEN>
User: Bearer <USER-TOKEN>

Example python request using Authlib:

# 'neanias' is a registered AAI provider using Authlib
token = oauth.neanias.fetch_access_token(grant_type='client_credentials')
# assumption: session contains the authorization token of the user
headers = {'Authorization': f'Bearer {token["access_token"]}',
            'User': f'Bearer {session["oatoken"]["access_token"]}'}
requests.get('https://atmo-flud.neanias.eu/api/files/service', headers=headers)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
      "/Demo/_small.dat": "8076765"
  },
  {
      "/Demo/_small2.dat": "2907690"
  }
]

Example response with error:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "User token is missing."
}
Request Headers
  • Authorization – required OAuth token to authenticate service

  • User – required OAuth token to authenticate user

Response Headers
Status Codes
  • 200 OK – array of <file-path> : <file-size>

  • 401 Unauthorized – The OAuth token (either service or user) is missing or is invalid

  • 403 Forbidden – Service or user is not allowed to access the endpoint.


GET /api/files/user

Get all files of the connected user, which are shared with atmo-flud service’s account in NEANIAS nextcloud. The request/response format is the same as in /api/files/service


POST /api/job/submit/eddy

Post a new scientific execution for the Eddy Covariance method.

Example HTTP request:

GET /api/files/service HTTP/1.1
Host: atmo-flud.neanias.eu
Authorization: Bearer <SERVICE-TOKEN>
User: Bearer <USER-TOKEN>
Content-Type: application/json

{
  "input_type": "SERVICE_FILE",
  "input_file": "Demo/_small.dat",
  "period": "18000",
  "limit": "3.5",
  "angle_from": "180",
  "angle_to": "300",
  "api_callback_address": "http://caller.neanias.eu/api/status/",
  "api_callback_token": "nA1cS12Z1RkdFpVN3hiM2JxUDVVcmpq"
}
Request Headers
  • Authorization – required OAuth token to authenticate service

  • User – required OAuth token to authenticate user

Form Parameters
  • input_type – the type of input file. The value should be one of the following: SERVICE_FILE for files provided by the service, USER_FILE for user file shared with the service, or URL for publicly accessible files.

  • input_file – The path of the file in nextcloud as retrieved by the api/file/* endpoints, or the url of a publicly accessible file.

  • period – required algorithm parameter in seconds. See here for more information.

  • limit – required algorithm parameter. See here for more information.

  • angle_from – required algorithm parameter. See here for more information.

  • angle_to – required algorithm parameter. See here for more information.

  • api_callback_address – optional parameter for receiving a notification of the execution result. If an address is provided then atmo-flud will make a post api_callback_address/<run-id> with the exit status of the calculation (completed or failed).

  • api_callback_token – optional parameter for validating that atmo-flud has post to the above address. If the caller application supplies this value, then atmo-flud will add it in the request header when making the above post. (X-Callback-Token: api_callback_token)

Response Headers
Status Codes
  • 200 OK – the run-id of the submitted execution

  • 401 Unauthorized – The OAuth token (either service or user) is missing or is invalid

  • 403 Forbidden – Service or user is not allowed to access the endpoint.

Example endpoint for receiving the execution’s result:

@route('/api/status/<run_id>', methods=['POST'])
def status_update(run_id: str):
    entry = request.json
    token_header = 'X-Callback-Token'

    if token_header not in request.headers:
        return f'{token_header} header missing', 401
    token = request.headers[token_header]
    if not token:
        return f'{token_header} header missing a value', 401

    if token != <supplied_token>:
        return f'Invalid callback token', 403

    # example output --> 540 : {'status': 'completed'}
    print(f'{run_id} : {entry}')

    return 'ok', 200

POST /api/job/submit/gradient

Post a new scientific execution for the Gradient method.

Example HTTP request:

GET /api/files/service HTTP/1.1
Host: atmo-flud.neanias.eu
Authorization: Bearer <SERVICE-TOKEN>
User: Bearer <USER-TOKEN>
Content-Type: application/json

{
  "input_type": "SERVICE_FILE",
  "input_file": "Demo/_small.dat",
  "period": "18000",
  "limit": "3.5",
  "height1": "5",
  "height1": "10",
  "height1": "20",
  "height1": "30",
  "z": "20",
  "api_callback_address": "http://caller.neanias.eu/api/status/",
  "api_callback_token": "nA1cS12Z1RkdFpVN3hiM2JxUDVVcmpq"
}
Request Headers
  • Authorization – required OAuth token to authenticate service

  • User – required OAuth token to authenticate user

Form Parameters
  • input_type – the type of input file. The value should be one of the following: SERVICE_FILE for files provided by the service, USER_FILE for user file shared with the service, or URL for publicly accessible files.

  • input_file – The path of the file in nextcloud as retrieved by the api/file/* endpoints, or the url of a publicly accessible file.

  • period – required algorithm parameter in seconds. See here for more information.

  • limit – required algorithm parameter. See here for more information.

  • height1 – required algorithm parameter. See here for more information.

  • height2 – required algorithm parameter. See here for more information.

  • height3 – required algorithm parameter. See here for more information.

  • height4 – required algorithm parameter. See here for more information.

  • z – required algorithm parameter. See here for more information.

  • api_callback_address – optional parameter for receiving a notification of the execution result. If an address is provided then atmo-flud will make a post api_callback_address/<run-id> with the exit status of the calculation (completed or failed).

  • api_callback_token – optional parameter for validating that atmo-flud has post to the above address. If the caller application supplies this value, then atmo-flud will add it in the request header when making the above post. (X-Callback-Token: api_callback_token)

Response Headers
Status Codes
  • 200 OK – the run-id of the submitted execution

  • 401 Unauthorized – The OAuth token (either service or user) is missing or is invalid

  • 403 Forbidden – Service or user is not allowed to access the endpoint.


GET /api/job/status/<run-id>

Query the status of a submitted scientific execution.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "active"
}
Request Headers
  • Authorization – required OAuth token to authenticate service

  • User – required OAuth token to authenticate user

Response Headers
Status Codes
  • 200 OK – The body contains the status of the job. It could be ‘active’, ‘completed’ or ‘failed’

  • 401 Unauthorized – The OAuth token (either service or user) is missing or is invalid

  • 403 Forbidden – Service or user is not allowed to access the endpoint.