REST API

[juro-ub]

Return JSON Output

Example call:
Call URL ->
http://localhost:8080/neg/rest/item/M1
http://localhost:8080/neg/rest/item/N1
http://localhost:8080/neg/rest/item/B1
http://localhost:8080/neg/rest/items/M1,M2,M3
http://localhost:8080/neg/rest/items/N1,N2,N3
http://localhost:8080/neg/rest/items/B1,N2,N3

[mtrojan-ub]

Note: I put this on DRAFT because i think this is a topic we should discuss on the community workshop in september (which technologies / output formats we should use, what requirements are there inside the community, and so on).

One possible candidate would be to create a Reconciliation API:
https://reconciliation-api.github.io/specs/draft/

[mtrojan-ub]

OK, so the workshop has shown that there is no real demand for a Reconciliation API in our community. There is however a demand for a regular JSON API, especially when it comes to reading single + multiple entities (especially on the Einzelbeleg level). So we can try to cover some simple cases within our current funding period. I will add some more comments.

[mtrojan-ub]

Instead of having 2 parameters like e.g. name + entity, we should use a single parameter which is the persistent identifier, e.g.

http://localhost:8080/neg/rest?pid=P7404

I think we should use a similar logic like in dojump.jsp. It would be good to have 1 central part of the code that knows how to map persistant identifiers + ids to corresponding model classes and their proper getter functions within the db namespace (not sure what the best spot would be - maybe inside the nppm.util namespace?)

Also i think that in the long term we should think about our URL structure for API calls, to make things more distinct and maybe also support some batch operations. What about:

• http://localhost:8080/neg/rest/item/P7404
• http://localhost:8080/neg/rest/items/P7404,P7406,P7407
  (- http://localhost:8080/neg/rest/search/... for later versions)

[juro-ub]

i have implemented the url structure like this:

http://localhost:8080/neg/rest/item/M1
http://localhost:8080/neg/rest/item/N1
http://localhost:8080/neg/rest/item/B1
http://localhost:8080/neg/rest/items/M1,M2,M3
http://localhost:8080/neg/rest/items/N1,N2,N3
http://localhost:8080/neg/rest/items/B1,B2,B3

[mtrojan-ub]

The first impression of this looks really good! Some more thoughts:

• Right now items + item return the same result type (array), but only items should return an array of objects. The item endpoint should return a single object
• The API should behave in a similar way like the gast interface => only items marked as ZuVeroeffentlichen should be shown. We should also make sure to throw the proper exceptions (e.g. IdInvalidException, IdNotFoundException, or IdNotPublicException) if somebody tries to access any invalid / improper IDs. Of course this could also lead to a whole batch request fail if only 1 id is wrong, but i think we can live with that state for now. At least there will be a proper error page be shown then (note than IdNotPublicException is not in master yet / see Exception error erweiterungen #272 for details or ask @rnaiser).
• The returned fields right now are rather plain, but we should do our best to sanitize them, e.g. if a field contains a string "null" or "-" we should either normalize that to null or entirely remove the field from the result object. Maybe we can also display date information in a better way, and so on
• I wonder if it's a good idea to show some kind of documentation if /rest is called without any endpoints (like a list containing the available endpoints with some examples, like item, items, ... and add some words to the documentation whenever we provide additional endpoints)

[juro-ub]

The first impression of this looks really good! Some more thoughts:

• Right now items + item return the same result type (array), but only items should return an array of objects. The item endpoint should return a single object

A single item is now returned as an object

• The API should behave in a similar way like the gast interface => only items marked as ZuVeroeffentlichen should be shown. We should also make sure to throw the proper exceptions (e.g. IdInvalidException, IdNotFoundException, or IdNotPublicException) if somebody tries to access any invalid / improper IDs. Of course this could also lead to a whole batch request fail if only 1 id is wrong, but i think we can live with that state for now. At least there will be a proper error page be shown then (note than IdNotPublicException is not in master yet / see Exception error erweiterungen #272 for details or ask @rnaiser).

Yes a proper error page is shown if the id is not available or not public

• The returned fields right now are rather plain, but we should do our best to sanitize them, e.g. if a field contains a string "null" or "-" we should either normalize that to null or entirely remove the field from the result object. Maybe we can also display date information in a better way, and so on

I have used a DateFormatter to format the date Objects.
I have implement a function sanitize.
If an entry has the value null, it is not part of the result object now.

• I wonder if it's a good idea to show some kind of documentation if /rest is called without any endpoints (like a list containing the available endpoints with some examples, like item, items, ... and add some words to the documentation whenever we provide additional endpoints)

I have implemented a help page for the url http://localhost:8080/neg/rest