Test: General

[jnehring]

• When we set header Accept: text/turtle then across all e-Services the output is not nicely formated
• Some parameters are shared across all e-Services, but they have different names and values in the e-Services. We should agree on the same parameter names and values for these parameters across all services.
  • input: The NIF / plaintext that we submit to the service. I suggest we make this a parameter called “input”.
  • inputType: the format of input (plaintext, text/turtle, text/json+ld). That implies that for GET requests the Content-Type header does not matter and for POST requests it should be multipart/form-data or application/x-www-form-urlencoded . But we should not make the Content-Type a required header and assume application/multipart/form-data as default value. If this turns out not to be efficient enough for large strings then we can also support Content-Type: application/x-www-form-urlencoded
  • Accept Header: This controls the output format. It is optional with default text/json+ld . For the first prototype you can also submit text/turtle
  • All parameters that are not request headers can be submitted as POST form-data variable or GET variable. POST form-data has a higher priority then GET.

[andish]

• We should avoid using multipart/form-data, but use Accept and Content-type HTTP headers for specifying input/output formats to keep the service API clean and simple as possible:
  • parameters in URL that are not sensitive (unsecure way), such as languages, domains etc
  • input document in POST body (secure way)
  • sensitive parameters as HTTP headers (secure way), keys, passwords, usernames etc
• Should use only POST method for submitting content to e-Services:
  • content must be encrypted over SSL because input and output can contain also confidential and sensitive data
  • URL lenght is restricted to ~2000 chars
  • URL must be encoded/decoded

[fsalliau]

+1 for API uniformity. Andis, do you mean we should abandon any GET requests?

[andish]

Yes, I think for enrichment services we could deny any GET request to avoid problems and provide all services in a single way:

• Post content to e-Entity
• Post content to e-Link
• Post content to e-Terminology
• Post content to e-Translation
• Post content to e-Publishing

For metadata issues (that are now uploaded separately from the NIF content) - maybe we have to find a way how to include them into the RDF (NIF) document, to be in line with common approach.

[m1ci]

Andis, do you mean we should abandon any GET requests?

The correct way is to submit data as body of a POST request, however, GET requests are VERY handy for developers and consumers because you can directly in your browser test the service. Note that by entering URL address in any browser is translated into a GET request. I suggest we support POST (primarily) and GET request (optionally).

[jnehring]

I see that putting only the NIF string in the POST body and defining the NIF serialization format using Content-Type header is the RESTful way and therefore clean API design. But in some cases this API design is not possible:

1. Sometimes we might want to put multiple variables in the POST body. To my knowledge this is only possible with Content-Type: multipart/form-data or application/x-www-form-urlencoded
2. We already have use cases with multiple variables in the POST body: e-Publishing needs to accept files and nif as input. We discuss to append a SKOS file to an e-Entity request in addition to the NIF data.

So there are e-Services that require Content-Type multipart/form-data or application/x-www-form-urlencoded. For uniform e-Service design I suggest that we use the same Content-Type for all POST requests.

I would not drop GET requests completely. They are useful for non-expert users who dont know about HTTP details. They require less configuration and can be tried out using the web browsers address bar. Our e-Services should accept the same parameters both from query string and POST body.

[m1ci]

Sometimes we might want to put multiple variables in the POST body. To my knowledge this is only possible with Content-Type: multipart/form-data or application/x-www-form-urlencoded

Don't understand the term multiple variables? you mean query parameters?

We already have use cases with multiple variables in the POST body: e-Publishing needs to accept files and nif as input. We discuss to append a SKOS file to an e-Entity request in addition to the NIF data

We define APIs which (almost) always are defined as a set of resource URIs. So, for the e-Publishing API you can have 1) resource defined for submitting the metadata (I think these are the files you are talking about) and 2) a resource for the main NIF document.

Examples:

POST /e-publishing/metadata/documents/

for submitting the metadata documents, and

POST /e-publishing/ebooks/documents/?metadata=some_id_here

for submitting the NIF which will be then converted to a eBook using the metadata files submitted in the previous call.

What do you think?

[jnehring]

About the term multiple variables: Here are two examples of POST requests with two variables in the body. Both encode two variables with variable1=value1 and variable2=value2. Note that the request body starts after the empy line after Content-Type.

POST /e-entity/dbpedia-spotlight HTTP/1.1
Host: rv1460.1blu.de:8080
Content-Type: multipart/form-data

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="variable1"

value1
----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="variable2"

value2
----WebKitFormBoundaryE19zNvXGzXaLvS5C

or

POST /e-entity/dbpedia-spotlight HTTP/1.1
Host: rv1460.1blu.de:8080
Content-Type: application/x-www-form-urlencoded

variable1=value1&variable2=value2

About having two endpoints for the same call: One principle about RESTful API design is that it is stateless. When we use two API calls for one function then it is not stateless. Also it complicates our codes a lot when one API call references to another API call and we have to store intermediate results somehow in the broker. When someone uploads a file then we should process the file and get of it as soon as possible so it does uses the servers memory as short as possible.

[andish]

When we use two API calls for one function then it is not stateless.

Not always true. If you use any DB that stores previously uplouded part of request it is still stateless webservice and can be balanced.

But - I think that multipart uploud should leave as any advanced service variation, primary e-services could accept normal POST request.

We have to think about simple and widely reusable services and not let the tehnologies and some issues lead us to hardly usable services.

[jnehring]

We agreed on encoding only NIF content in post body instead of using multipart post requests. The discussion about parameter names moved to #14