Operations

Every API you will build will have at least one operation. A operation is a collection of fulfillment that will be processed during execution and responses.

Triggers

An operation will be triggerd by either an:

• API
• Timebased
• Reference-Call

Triggered by API

The most common trigger is the API trigger. Basically you are building yourself an new API then you will have an operation for each HTTP-Endpoint you are building. Meaning 1 HTTP-Endpoint = 1 Operation. When you want your operation to be triggered by endpoint simply use the same name as the request in your openapi specification:

'HTTP-Method /ENDPOINT_PATH'

HTTP-METHOD	Endpoint	Name Pattern
GET	/news	'GET /news'
POST	/news/{id}	'POST /news/{id}'
DELETE	/news/comment/{id}	'DELETE /news/comment/{id}'

Triggered by Time

By adding a cron trigger you can set a timebased execution of your operation.

Triggered by Reference-Call

An operation can also be triggered by another operation. This is a reference-call trigger.

Every operation can have one to more triggers at the same time.

An operations consists of three sections:

1. Fulfillments
2. Responses
3. Triggers
4. Reference-Call

An operation must have at least one fulfillment and either a response or a trigger or both.

operations:

  'get /news':
    fulfillments:
      ....

    responses:
      ....

    triggers: 
      ....

Fulfillments

The extensive topic of fulfillments is available under: Fulfillments

Responses

After all fulfillments have been executed APICHAP will build the response of your operation. You may specify a list of responses as you are able to use different kind of responses depending on the statuscode. A response has the following attributes:

Field	Description	Mandatory
name	A name for identification	x
default	True or False. Each operation must have a default response. The default response is used if no error occoured.	x
statuscode	The http statuscode you want to return.	x
schema	Find out how to construct your json schema here: Schema

A response schema will always be of dataformat: JSON

# A simple response sending http statuscode 200 and building a simple Json
responses:
  - name: success
    statuscode: 200
    default: true
    schema:
      id: VALUE(contactFF, $.results[0].id)
      firstname: VALUE(contactFF, $.results[0].properties.firstname)
      lastname: VALUE(contactFF, $.results[0].properties.lastname)
      email: VALUE(contactFF, $.results[0].properties.email)
      last_sync: VALUE(contactFF, $[0].update_time)

Triggers

It´s possible to execute an operation using a timebased trigger.

Triggers are not building a response as there is nowhere they are able to return data.

A trigger consists of:

Field	Description	Mandatory
name	A name for identification	x
cron	A timebased cron condition: 0 0 * * * *	x

# Run this operation every minute
'only_timebased_operation':

  triggers:
    - name: minutely_trigger
      cron: 0 * * * * *

  fulfillments:

    - name: do something in this fulfillment
      type: READ
      ....

# This operation will be triggered by the request GET /test as well as timebase every hour.
'GET /test':

  triggers:
    - name: every_hour
      cron: 0 0 * * * *

  fulfillments:

    - name: do something in this fulfillment
      type: READ
      ....

  responses:
  # As this operation has an HTTP trigger (GET /test) it needs a response.

Reference-Call

Sometimes multiple operation are sharing some functionality. In this case you are able to execute an operation from another operation. This is called a reference call. When calling another operation you are able to give it some input parameters or a whole input body. The referenced operation will be executed and return its response as json which the original fulfillment can then use to continue with.

Defining a Reference:

You can define a reference to another operation using the fulfillment type: reference. The operationName must match the name of the operation you wish to call. You can also pass parameters to the referenced operation. All parameters will be available as PARAM in the called operation. If you want to pass an entire request body, you can do so by naming the parameter body, which can be accessed using BODY() in the referenced operation.

# Call this operation to update the attendees
- name: reference_update_attendees
  type: reference
  operationName: operation_update_attendees
  parameters:
    userid: VALUE(i, $.id)
    name: VALUE(i, $.name)
    body: VALUE(i, $.person) # -> In body you are able to pass more advanced structured then simple primitive values.

In your operation operation_update_attendees you are then able to get the parameters by using PARAM(userid) or BODY() like usual.

Full Example

A full operation to get a news item from a database could look like this:

'get /news/{id}':
  fulfillments:
    - name: news
      type: READ
      datasource: db
      instructions:
        - sql: 
            query: Select id, title from news WHERE id = ? 
            parameters: 
              - param: PARAM(id)

    - name: news_images
      type: READ
      datasource: db
      instructions:
        - sql: 
            query: Select imageurl from news_images WHERE imageId = ?
            parameters:
                - param: PARAM(id)

  responses:
    - name: success
      statuscode: 200
      default: true
      schema:
        id: VALUE(news, $[0].id)
        title: VALUE(news, $[0].title)
        images:
          list: VALUE(news_image, $)
          item:
            imageurl: VALUE(@, $.imageurl)