pipelines: enhance API documentation

Here is a description of the new CRUD operations of pipeline templates, and also the use of a template.

Use pipeline template

Uses a stored pipeline template on a given NIF or plain text input.

Method: POST

Endpoint: /pipelining/chain/{id}

id: Path parameter: id of the pipeline template to use.

Content-Type: HTTP Header parameter, can be one of text/turtle, application/json, application/ld+json, application/n-triples, application/rdf+xml, text/n3, text/plain, depending on the body.

Body: The input for the pipeline chain. This can be a NIF or plain text document.

Responses:

200 OK with the output of the last request in the pipeline chain in the body.
400 BAD REQUEST if the request cannot be processed.
401 UNAUTHORIZED if the user is not logged in.
404 NOT FOUND if the requestes template is not found.
500 Internal Server Error if something unexpected goes wrong.
Create pipeline template

Creates and stores a pipeline on the server the request is sent to. The response contains the id of the created pipeline, which is to be used in further methods.

Method: POST.

Endpoint: /pipelining/templates/.

Content-Type: HTTP Header parameter, should be application/json.

persist: Optional parameter: values can be true or false. Indicates whether to persist the pipeline forever (true) or for just one week (false). If not given, it defaults to false.

visibility: Optional parameter: values can be PRIVATE or PUBLIC. A template with visibility PUBLIC is visible and usable by anyone. A template with visibility PRIVATE is only visible and usable by the owner. The default value is PUBLIC.

Body: The pipeline template as JSON string: It represents an object with a label, a description and a list of request objects. Example:

{
  "label": "Spotlight-Link",
  "description": "Recognises entities using Spotlight en enriches with geo information.",
  "serializedRequests": [
    {
      "method": "POST",
      "endpoint": "http://api.freme-project.eu/current/e-entity/dbpedia-spotlight/documents",
      "parameters": {
        "language": "en"
      },
      "headers": {
        "content-type": "text/plain",
        "accept": "text/turtle"
      }
    },
    {
      "method": "POST",
      "endpoint": "http://api.freme-project.eu/current/e-link/documents/",
      "parameters": {
        "templateid": "3"
      },
      "headers": {
        "content-type": "text/turtle",
        "accept": "text/turtle"
      }
    }
  ]
}

The fields of the returned object are:

label: The name of the pipeline template.
description: a description of the pipeline template.
serializedRequests: the chained requests as described in /pipelining/chain.

Responses:

200 OK with the generated pipeline. The id, persist parameter and visibility are included in the body if everything goes well. E.g.:

{
  "id": 1445246379051,
  "label": "Spotlight-Link",
  "description": "Recognises entities using Spotlight en enriches with geo information.",
  "persist": false,
  "visibility": "PUBLIC",
  "owner": "userwithpermission",
  "serializedRequests": [
    {
      "method": "POST",
      "endpoint": "http://api.freme-project.eu/current/e-entity/dbpedia-spotlight/documents",
      "parameters": {
        "language": "en"
      },
      "headers": {
        "content-type": "text/plain",
        "accept": "text/turtle"
      }
    },
    {
      "method": "POST",
      "endpoint": "http://api.freme-project.eu/current/e-link/documents/",
      "parameters": {
        "templateid": "3"
      },
      "headers": {
        "content-type": "text/turtle",
        "accept": "text/turtle"
      }
    }
  ]
}

The fields of the returned object are: * id: the generated id if the template. This is also the timestamp of creation, in milliseconds. * label: The name of the pipeline template. * description: a description of the pipeline template. * persist: if false, the template will not automatically be deleted; if false it will live only for one week. To be implemented. * owner: the owner, in this case the creator, of the pipeline template. * serializedRequests: the chained requests as described in /pipelining/chain.

400 BAD REQUEST if the request cannot be processed, e.g. in case of a JSON syntax error.
401 UNAUTHORIZED if the user is not logged in.
500 Internal Server Error if something unexpected goes wrong.
Update pipeline

Updates a pipeline template on the server the request is sent to.

Method: PUT.

Endpoint: /pipelining/templates/{id}.

Content-Type: HTTP Header parameter, should be application/json.

id: Path parameter: the id of the pipeline.

persist: Optional parameter: values can be true or false. Indicates whether to persist the pipeline forever (true) or for just one week (false). If not given, it defaults to false.

owner: Optional parameter: the new owner of the pipeline.

Body: The updated pipeline template as JSON object, as described in Create pipeline template.

Responses:

200 OK with the updated pipeline in the body if all goes well (see Create pipeline template for an example).
400 BAD REQUEST if the request cannot be processed;
403 FORBIDDEN if the user has no permission to update the template.
404 NOT FOUND if the pipeline does not exist.
Read pipeline

Returns the pipeline with the given id found on the server the request is sent to.

Method: GET

Endpoint: /pipelining/templates/{pipelineid}

id: Path parameter: the id of the pipeline.

Responses:

200 OK with the requested pipeline in the body if all goes well (see Create pipeline template for an example).
404 NOT FOUND if the requested pipeline does not exist.
Read pipelines

Returns is list of all visible pipeline templates on the server the request is sent to.

Method: GET

Endpoint: /pipelining/templates

Responses:

200 OK with a list of visible pipelines in the body if all goes well. Example:

[
  {
    "id": 1445259245610,
    "label": "Spotlight-Link",
    "description": "Recognises entities using Spotlight en enriches with geo information.",
    "persist": false,
    "visibility": "PUBLIC",
    "owner": "userwithpermission",
    "serializedRequests": [
      {
        "method": "POST",
        "endpoint": "http://api.freme-project.eu/current/e-entity/dbpedia-spotlight/documents",
        "parameters": {
          "language": "en"
        },
        "headers": {
          "content-type": "text/plain",
          "accept": "text/turtle"
        }
      },
      {
        "method": "POST",
        "endpoint": "http://api.freme-project.eu/current/e-link/documents/",
        "parameters": {
          "templateid": "3"
        },
        "headers": {
          "content-type": "text/turtle",
          "accept": "text/turtle"
        }
      }
    ]
  },
  {
    "id": 1445259245765,
    "label": "NER-Translate",
    "description": "Apply FRENE NER and then e-Translate",
    "persist": false,
    "visibility": "PRIVATE",
    "owner": "userwithpermission",
    "serializedRequests": [
      {
        "method": "POST",
        "endpoint": "http://api.freme-project.eu/current/e-entity/freme-ner/documents",
        "parameters": {
          "language": "en",
          "dataset": "dbpedia"
        },
        "headers": {
          "content-type": "text/plain",
          "accept": "text/turtle"
        }
      },
      {
        "method": "POST",
        "endpoint": "http://api.freme-project.eu/current/e-translation/tilde",
        "parameters": {
          "source-lang": "en",
          "target-lang": "fr"
        },
        "headers": {
          "content-type": "text/turtle",
          "accept": "text/turtle"
        }
      }
    ]
  }
]

404 NOT FOUND if the pipeline does not exist.
Delete pipeline

Deletes the pipeline with a given id.

Method: DELETE

Endpoint: /pipelining/templates/{id}

id: Path parameter: the id of the pipeline template.

Responses:

200 OK if all goes well. The body is a text/plain message: "The pipeline was sucessfully removed."
403 FORBIDDEN if the user has no permission to update the template.
404 NOT FOUND if the pipeline does not exist.

freme-project / freme-project.github.io

pipelines: enhance API documentation #101

Use pipeline template

Create pipeline template

Update pipeline

Read pipeline

Read pipelines

Delete pipeline