RESTful API

[x0bandeira]

A RESTful API would make integration and learning curve much simpler

[monnand]

Yes. I agree. However, this would break the API. I think I will make this change in version 2.0, which is currently under development (well.. sort of. I almost suspended the development in recent months for personal reasons. I will restart working on this project today.)

[monnand]

@rafaelbandeira3 BTW, Any suggestions about the RESTful API? I'm considering something like:

• /<service>/<subscriber>/device, GET. list all devices under the subscriber.
• /<service>/<subscriber>/msg, POST. push a notification to all delivery points under ths subscriber.
• /<service>/<subscriber>/device, POST. Add a devices to the subscriber.
• /<service>/provider, POST. Add a provider to the service.

[x0bandeira]

Some objective considerations on API design, things may vary as you have more understanding of the underlying domain than I do:

• Names should be in plural form so endpoints can reference a collection and a member without requiring more work by the client: GET /<service>/<subscriber>/devices and GET /<service>/<subscriber>/devices/<device>; POST /<service>/providers and GET /<service>/providers
• Names should not be abbreviated as different people abbreviate things differently: GET /<service>/<subscriber>/messages
• State should be referenced by payload for extensibility and to prevent increasing complexity on the client, as URL is constant for all types of resources and payload can differ as it is just a map: GET /<service>/devices and GET /<service>/devices?subscriber_id=<subscriber> and GET /<service>/devices?created_at=2014-12-24 and POST /<service>/devices "subscriber_id=<subscriber>..."
• Endpoints should be prefixed for forward compatibility, so whenever we add other features like server health check, or UI, or metrics, they are all neatly namespaced: GET /services/<service>

[x0bandeira]

From a release management standpoint, assuming the functionality of the RESTful endpoints is equivalent to existing endpoints, and thus doesn't require changes to the existing domain, just to the HTTP handling layer, then the RESTful API should be added before 2.0 wherever it doesn't conflict with the existing API, or all namespaced if it conflicts in any point. So existing functionality remains unchanged but new users already start building off the intended design without having to wait for another batch of functionality that doesn't change how they work. Then documentation for the old API should still live but with a deprecation disclaimer.

[monnand]

Thank you, @rafaelbandeira3 ! Your comments answered a lot of my questions. This really helped me a lot. If everything works well, I can work on this project (almost) full time after this holiday season.

[mishan]

@command3r We're working on making uniqush-push more REST-ful, expect to see some improvements pushed upstream very soon.

[tleyden]

If you used Swagger to document the REST API then client libraries in various languages could be automatically generated.

[TysonAndre]

Additionally, for a new restful API, should set proper content-type of application/json in the response

• Mandate usage of POST/PUT as appropriate for state changes (Creating PSPs, pushing, subscribing?)
• Maybe DELETE for removing a device or endpoint?

Another idea for a rest API would be support for various forms of authentication in the config for access within a datacenter, e.g. shared secret in HTTP header (Even with that, one should prevent the uniqush service from being publicly accessible)

Future API changes should have different endpoint paths (E.g. beginning with /v2/), and exist alongside old endpoint paths for a few releases to make migration easier.

Still haven't decided on a RESTful choice of endpoint paths.

Error messages should be more descriptive, include all of the (guaranteed to be) missing fields instead of just the first one? (Can add to current rest version)

• OPTIONS is nice to have, but not essential (Self-describing API)