Version 1.0.0-RC1 (release candidate)

[mikesteez]

We implemented the echo API yesterday in the reference connector.

It is somewhat unconventional from a REST perspective to have a GET with a query parameter with a complex object such as `<?xml version="1.0" encoding="utf-8"?>

Test echo ` Normally query parameters are simple types such as id:s or strings. It is also prohibited to use a body with GET requests. We suggest to keep the POST for the echo API.

[wrygiel]

I think GET can be allowed for requests as long as it's doesn't change things. You're absolutely right, the XML shouldn't be passed via GET parameters though (it's ugly), however (as we have admitted in the docs) it's an exception, and it has its purpose in this case - we want to make it really easy for the developers to test this API inside their own browsers (once they install a client certificate in them, they can issue GET requests directly to partner Echo APIs).

[wrygiel]

BTW, in parallel, we've been working on Registry Service implementation and have changed some things in the Registry and Discovery API specs. There are two release candidate versions to review. Take a look when you have some time!

[wrygiel]

It is also prohibited to use a body with GET requests.

Note, that currently it is required to pass the XML via the application/x-www-form-urlencoded vars parameter. That is, raw body is not used in neither GET nor POST request.

[mikesteez]

I agree that we need an easy way to test the API. However, it will not be easy to make a valid request from a browser with the XML payload in the query parameter, especially if it will be application/x-www-form-urlencoded. I presume that this way of calling the API will also not be used in any other cases?

The W3C recommendation says

The content type "application/x-www-form-urlencoded" is inefficient for sending large quantities of binary data or text containing non-ASCII characters. The content type "multipart/form-data" should be used for submitting forms that contain files, non-ASCII data, and binary data.

W3C

I suggest a simpler GET with just a query parameter and a more complex POST with a full XML document.

[wrygiel]

it will not be easy to make a valid request from a browser with the XML payload

It should be quite easy in most cases. Note, that most browsers do the proper encoding automatically. For example, try pasting this into Chrome location bar:

http://example.com/echo?vars=<vars xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/master/request-vars.xsd"><echo>Test echo</echo></vars>

The browser will encode it as application/x-www-form-urlencoded "on the fly", so we will end up with a valid Echo API request:

http://example.com/echo?vars=%3Cvars%20xmlns=%22https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/master/request-vars.xsd%22%3E%3Cecho%3ETest%20echo%3C/echo%3E%3C/vars%3E

(However, the browser will fail to fix our encoding if our XML contains the & character.)

I presume that this way of calling the API will also not be used in any other cases?

This is a de-facto standard for both GET and POST requests issued from HTML forms. Can you explain why you think it's a bad idea to reuse this standard?

The content type "application/x-www-form-urlencoded" is inefficient for sending large quantities of binary data or text containing non-ASCII characters.

As far as I know, we'll be using UTF-8 characters only, so it seems efficient. Do you think that we should use other encoding?

I suggest a simpler GET with just a query parameter and a more complex POST with a full XML document.

We wanted the developers to be efficient in encoding and decoding data in all these formats - that's why we're mixing them up here this way. Do you think that we have exaggerated? If you do, then perhaps you're right, and we should make it simpler... hmm....

[mikesteez]

This is a de-facto standard for all GET and POST requests issued from HTML forms. Can you explain why you think it's a bad idea to reuse this standard?

Are we building a REST API or a browser based system?

With a REST API you specify the media type, i.e. application/vnd.erasmuswithoutpaper+xml

GET /ewp/agreements?iia_id=5a3c20fc-bf17-4e78-bd5f-668b29f7e250 Host: ewp.ladok.se Accept: application/vnd.erasmuswithoutpaper+xml

And the response: `<?xml version="1.0" encoding="utf-8"?>

Mobility goes here ` I don't see a need for urlencoding XML documents for request parameters. `application/x-www-form-urlencoded` is perfectly fine for sending key/value-pairs if we want that. Our API should be simple to use and understand. The response representations and the representations we use to create information can be very complex, but not the search api.

[wrygiel]

I think you have missed the purpose of the Echo API.

In general, we won't be using XML documents for request parameters - we will be sending key-value pairs in 90% of the cases. As stated in the specs, we do this in Echo API only as exercise - we are purposefully exposing a pessimistically-complex interface, just to make sure that developers' implementations will be prepared to deal with it.

[wrygiel]

Currently, all APIs use application/x-www-form-urlencoded encoding for requests. Of course, we can change that in cases of specific APIs, but mostly we will probably stick with this.

[wrygiel]

However, now I'm afraid, that other developers might also miss this purpose, and this might lead to some bad feelings. We don't want that. Perhaps it will be best to remove XML from Echo API request and keep it simple.

[wrygiel]

See https://github.com/erasmus-without-paper/ewp-specs-api-echo/issues/5

[wrygiel]

I'm releasing this revision as version 1.0.0.

There are some open topics regarding architecture, which will probably influence Echo API considerably, but these will take some time to resolve. We need to release Discovery 4.0.0, Registry 1.0.0 and Echo 1.0.0 in order to keep them as base references.