Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

SINCE VERSION 1.0

What is the PIPEFORCE HTTP API?

The PIPEFORCE HTTP API allows you to manage any aspect of the PIPEFORCE platform via RESTful HTTP calls. Here is a list of the most important endpoints:

Path

Method

Description

/api/v3/pipeline

POST

Execute adhoc
pipeline YAML or JSON given in the body. The pipeline is not stored.

  • The request body will become the body of the pipeline.

  • Request params will be set in vars scope of the pipeline.

  • Request and response can be accessed via ${request} and ${response} object in the pipeline.

/api/v3/pipeline:{path}

PUT

Store
the pipeline YAML given in the body in the property store at {path}. Overwrite any existing one.

/api/v3/pipeline:{path}

POST

Load and execute
the persisted pipeline at {path} from the property store:

  • The request body will become the body of the pipeline.

  • Request params will be set in vars scope of the pipeline.

  • Request and response can be accessed via ${request} and ${response} object in the pipeline.

/api/v3/pipeline:{path}

GET

Return
the pipeline persisted at {path} from the property store.

/api/v3/pipeline:{path}

DELETE

Delete
the persisted pipeline at {path} from the property store.

/api/v3/command:{name}

POST
GET

Execute
a single command given by name {name}.

  • The request body in POST requests will become the body of the command.

  • Request params of POST or GET requests will become the params to the command.

See the Command API documentation for a listing of all built-in commands.

For more details see the API Documentation.

Execute adhoc pipeline

In order to execute an adhoc pipeline (= execute a pipeline without persisting it), you can send a HTTP POST request to this endpoint url with the pipeline script as YAML or JSON in the body:

https://hub-NS.pipeforce.net/api/v3/pipeline

The most common usage scenario is to send a pipeline YAML script to the server and execute it there without storing it.

Because of security, adhoc pipelines are limited in the features what they can do. If you need full functionality, consider to execute a persisted pipeline instead.

Example

Let's for example assume an adhoc pipeline like this to be executed at server side:

pipeline:
  - body.set:
      value: "Today is: ${@date.now()}"

This pipeline can be executed at server side by sending it in the body of a HTTP POST request with a header of Content-Type: application/yaml, like this HTTP message log shows:

POST /api/v3/pipeline HTTP/1.1
Host: https://hub-NS.pipeforce.net
Content-Type: application/yaml
Authorization: Basic bXl1c2VybmFtZTptcGFzc3dvcmQ=
Content-Length: 63

pipeline:
  - body.set:
      value: "Today is: ${@date.now()}"

As a cURL command, this could be executed in your terminal like this:

curl --location 'https://hub-NS.pipeforce.net/api/v3/pipeline' \
--user 'myusername:mypassword' \
--header 'Content-Type: application/yaml' \
--data-raw 'pipeline:
  - body.set:
      value: "Today is: ${@date.now()}"'

And here you can see a Postman snippet as well (replace {{hubBaseUrl}} by your own hub url):

The response result of all of these requests would be something like this:

Today is: 31.07.2023, 15:54:16

You can also send and execute a pipeline in JSON format this way. In this case you have to set the Content-Type header to application/json instead.

Example: No body

In case you would like to execute a pipeline YAML script without a message body, you can run this:

curl -u 'username:password' \
  -X POST "https://hub-try.pipeforce.org/api/v3/pipeline" \
  -H "Content-Type: application/yaml" \
  --data-binary @- << EOF
pipeline:
 - drive.read:
     path: /my.pdf
 - pdf.stamp:
     text: "Hello World!"
 - drive.save:
     path: /my-stamped.pdf
EOF

Example: With body embedded in the pipeline

In case you would like to execute a pipeline YAML script with message body, which is embedded inside the YAML, you can run it like this example shows:

curl -u 'username:password' \
  -X POST "https://hub-try.pipeforce.org/api/v3/pipeline" \
  -H "Content-Type: application/yaml" \
  --data-binary @- << EOF
pipeline:
  - log:
      message: "BODY: ${body.text}"

body: {"text": "Hello World!"}
EOF

Example: With multipart body

Let's assume you would like to execute a pipeline and additionally processing one or more files in this same pipeline which must be placed in the body.

Here’s an example of an HTTP multipart request as defined by the HTTP specification. This example does multiple steps in one request: It uploads a PDF, puts a new text on this PDF and finally stores it at server side:

curl -u 'username:password' \
  -X POST 'https://hub-try.pipeforce.org/api/v3/pipeline' \
  -F 'pipeline="pipeline:
        - pdf.stamp:
            text: \"Hello World!\"
        - drive.save:
            path: /my-stamped.pdf "' \
  -F 'file=@/my1.pdf' \

Note that the pipeline has the part name pipeline and one or more files must all have the name file.

Execute persisted pipeline

A persisted pipeline is one which is stored in the property store.

It is possible to load and execute such a persisted pipeline from the property store by sending a HTTP POST request:

https://hub-NS.pipeforce.net/api/v3/pipeline:{path}
  • Replace NS by your own namespace.

  • Replace {path} by the path of the pipeline in the property store.

Instead of using the property path, you can also set the uuid of the pipeline property:

https://hub-NS.pipeforce.net/api/v3/pipeline:uuid:{uuid}
  • Replace NS by your own namespace.

  • Replace {uuid} by the uuid of the pipeline property to be loaded and executed.

This uuid-approach has the advantage that it will work even if the pipeline has been moved / renamed to a different path.

Any request parameter given will be set as vars to the pipeline.

In case there is a body in the request, it will be set as initial body to the pipeline.

If header ContentType is set to application/json the body will be parsed to a JSON object and provided as initial body value. Otherwise, the initial body will be provided as content object or it will be null in case no request body was set.

For more details about managing persisted pipelines, see the API documentation.

Example: Load and Execute persisted pipeline

In this example, a pipeline persisted under path global/app/myapp/pipeline/mypipeline will be loaded and executed at the backend without any body or request parameters:

curl -u 'username:password' \
  -X POST 'https://hub-NS.pipeforce.net/api/v3/pipeline:global/app/myapp/pipeline/mypipeline'

Example: Persist a pipeline (save it in property store)

In this example a new persisted pipeline will be created under path global/app/myapp/pipeline/newpipeline:

curl -u 'username:password' \
  -h 'Content-Type: application/yaml' \
  -X PUT 'https://<hostname>/api/v3/pipeline:global/app/myapp/pipeline/newpipeline' \
  --data-raw 'pipeline:
    - log:
        message: "HELLO WORLD!"'

  • No labels