PIPEFORCE HTTP API
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. You can setup automation and data integration apps. Execute commands and pipelines. Manage users, webhooks, configs, gateway endpoints and much more using this API.
Here is a list of the most important entry-endpoints:
Path | Method | Description |
---|---|---|
| POST | Execute adhoc
See: https://pipeforce.github.io/api#/Pipeline%20API 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. |
| PUT | Store |
| POST | Load and execute
|
| GET | Return See: |
| DELETE | Delete See: |
| PUT | Create, read, update and delete persisted JSON documents, attachments and other data types in the persistence DB, called the Property Store. See: |
| POST | Execute
Since VERSION 10 this default behaviour can be changed by passing the optional request parameter See here for a full list of available commands: |
For more details see the API Documentation.
Execute pipeline (adhoc)
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.
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.
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:
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:
Example: No body
In case you would like to execute a pipeline YAML script without a message body, you can run this:
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:
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:
Note that the pipeline has the part name pipeline
and one or more files must all have the name file
.
Execute pipeline (persisted)
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:
Instead of using the property path, you can also set the uuid of the pipeline property:
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:
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
: