| Status | ||||
|---|---|---|---|---|
|
| Table of Contents |
|---|
What is the PIPEFORCE
...
Rest API?
The PIPEFORCE HTTP Rest API allows you to manage any aspect of the PIPEFORCE platform via RESTful HTTP calls. You can setup automation and data integration apps. Execute commands and automation pipelines remotely. Manage users, webhooks, configs, gateway endpoints and much more using this API.
A full list of all available endpoints of this API can be found in the API documentation.
Here is a list an overview of the most important entry-endpoints:
Path | Method | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Execute adhoc
See: https://pipeforce.github.io/api#/Pipeline%20API
| ||||||||||||||||||||||||||||||
|
| Store | ||||||||||||||||||||||||||||||
|
| Load and execute
| ||||||||||||||||||||||||||||||
|
| Return | ||||||||||||||||||||||||||||||
|
| Delete | ||||||||||||||||||||||||||||||
|
| Create, read, update and delete persisted JSON documents, attachments and other data types in the persistence DB, called the Property Store. | ||||||||||||||||||||||||||||||
|
| Execute
See the Command API documentation here for a listing of all built-in commands.full list of available commands: |
For more details see the API Documentation.
Execute a command via Rest API
Every command can also be executed via Rest API. The URL format for calling such a command looks like this:
| Code Block |
|---|
https://hub-{instance-name}/api/v3/command:{name} |
Whereas {instance-name} must be replaced by your own instance name and {name} must be replaced by the name of the command to be called.
Every command can be called via HTTP GET or HTTP POST. The request parameters will become the parameters to the command. In case of a HTTP POST request, the body of the POST request will become the body of the command.
| Info | ||||||
|---|---|---|---|---|---|---|
Since
?params=body along with the command call. In this case the input to the command will be set to null. And the request body can contain a JSON or YAML which will be passed as command parameters. |
| Info |
|---|
Note: It is possible to restrict the permission by users, roles and groups who is allowed to call commands. See Groups, Roles and Permissions for more details. |
Execute
...
adhoc pipeline via Rest API
| Info |
|---|
For security reasons, executing adhoc pipelines is by default restricted to admin, support and developer users in DEV stage only. For production stage you should always consider to use persisted pipelines instead. |
...
| Info |
|---|
|
The most common usage scenario is to send a pipeline YAML script to the server and execute it there without storing it.
...
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:
| Code Block | ||
|---|---|---|
| ||
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:
| Code Block | ||
|---|---|---|
| ||
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.
...
Note that the pipeline has the part name pipeline and one or more files must all have the name file.
Execute
...
persisted pipeline via Rest API
A persisted pipeline is one which is stored in the property store.
...
| Code Block |
|---|
https://hub-NS.pipeforce.net/api/v3/pipeline:{path} |
| Info |
|---|
|
...
| Code Block |
|---|
https://hub-NS.pipeforce.net/api/v3/pipeline:uuid:{uuid} |
| Info |
|---|
|
...
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:
| Code Block | ||
|---|---|---|
| ||
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:
...