search

riigikogu-kantselei / api

Public issue tracker for Open data API at the Chancellery of the Riigikogu
https://api.riigikogu.ee/
GNU General Public License v3.0
10 stars 0 forks source link

REST suggestions #4

Open moll opened 7 years ago

moll commented 7 years ago

Hey,

I'd recommend reviewing the endpoints with REST principles in mind. It currently as elements of both REST and ad-hoc RPC (remote procedure call). Before I start evangelizing, are RESTful principles already something the API aims towards? :)

The RPC-ness of the endpoints is best exemplified by the /search endpoints. Proper REST-fulness, however, is also there with /users/{uuid}/speeches/last.

moll commented 7 years ago

There are peculiarities in the REST-like endpoints, too.

For example, /users/{uuid}/speeches supposedly supports filtering by co-speakers. Co-speaker UUIDs are supposed to be serialized in one query parameter:

/users/{uuid}/speeches?uuid=123,456

That's unnecessarily ad-hoc. The array syntax for query parameters is pretty [de facto] standard and should be used instead:

/users/{uuid}/speeches?uuid[]=123&uuid[]=456
moll commented 7 years ago

Another peculiarity: Resource endpoints return arrays that I'd argue don't make sense.

https://aavik.riigikogu.ee/api/ems/v1/documents/ba458175-b3e3-472e-8115-4ac291b8e4dc

The above returns an object with a nested array {"result": [...]} rather than the document object itself. I'd argue resource endpoints shouldn't ever return more than one response, so wrapping it in an array is redundant.