Version Numbers in Public APIs

Version Numbers in Public APIs
februari 14, 2013 squeedconfig

I’ve been playing with MangoSpring’s MangoApps Enterprise Edition Complete OpenAPI. It’s a fairly straight forward thing where you typically POST or PUT a JSON structure (or XML) that needs to match some spec and you get JSON (or XML) back.

I also see two, three things that I – in my very humble opinion – typically miss in most APIs.

Version Numbers

A year from now, or even two months, or tomorrow – I have no idea if I’m still complying with the current API. Sure, one way of solving this problem is to never remove anything, and never modify anything so that existing clients would have to change or update. I’m just not a fan of this approach.

Push

This is yet another API where you have to pull and pull and pull – there are no hooks for getting a notification pushed when something happens (such as a user posting a status update on a project wall).
(Workaround: start parsing e-mail content. Hopefully they contain custom headers that can be easily used.)

OAuth

To integrate with MangoApps, you need to store a base64 encoded version of an account’s password. I’d really prefer to use OAuth2 tokens and have that kind of control. It’s not a huge difference, but exposing the password exposes ”everything” that user account has access to. With a token that limits access to the public Open API only, you know the limits of that API at least. Preferably, you could limit parts of the API as in having the client request access to parts of the API which can be granted or not, and revoked.

Protocol/Schema Validation

This is clearly a love/hate thing, but having spent too long on tracing down things like: ”it’s not called `userid` in the protocol (as in the free text documentation), it’s `username`” without any proper error messages, you start longing for that JSON/XML schema …

Completeness

There’s a couple of things missing: ”Ideas” and ”Wikis” aren’t in there at all as far as I can see; when you post status updates you can’t control whether to enable/disable previews of the first URL in the post; ”to

    multiple users, send the User IDs as a comma separated string”; there are input fields marked REQUIRED which aren’t part of the example calls listed.

    Reference Implementations

    I assume MangoSpring do their regression testing of the OpenAPI using curl and diff. On one hand, I think that’s perfectly fine: that way you test your API at the lowest level and don’t accidentally miss out on bugs ”covered” behind some client library. On the other hand, zero reference implementations typically means no-one is using this for anything useful. (Our stuff is not yet used for anything useful, but we hope for that to happen eventually. The currently very embryonic stuff/spike is at GitHub.)

    Conclusion

    It’s obvious their own clients use some other API. I didn’t set out to give a short review of the API here – it just ended up that way. 🙂

    I simply wanted to ask: ”Do you think version numbers belong in an API, or an API’s endpoint URI?”

    1 Kommentar

    1. Fredrik Wendt 5 år sedan

      Oh – and a ”ping” or simple echo method that can be used to simply verify that the communication is working. The login and logout method might be enough here though, but still – it’s a nice addition that typically doesn’t cost any resources.

    Lämna ett svar

    E-postadressen publiceras inte. Obligatoriska fält är märkta *

    *

    Denna webbplats använder Akismet för att förhindra skräppost. Läs mer om hur dina kommentarsuppgifter behandlas.