Lots of people expose APIs based on endpoints and not client libraries.
Two applications:
- Frontend interface
- Backend delivery API
Always had a client to talk to the backend api, so felt natural to expose that.
Have 6 clients: Java, .NET, Node.js, PHP, Ruby, Python
PHP library was made by MoJ, we consumed this to properly support it.
The client libraries are really thin, take in parameters and pass them through as JSON. Uses JWT for authentication.
We're all python devs. Been able to turn to different parts of GDS for help for some other languages.
Struggled with .NET stuff, second class citizen treatment, not one on the team racing to fix those issues.
No one understood best practices for PHP.
The work is not too difficult since they're thin clients.
Lots of confusing packaging and releases processes to learn. Tough to keep on top of.
Especially for .NET, only runs on Windows, so we needed to fire of calls to Appveyor. Pain when the builds fail to get the error logs. But... .NET has improved, core has come out, so hopefully we can get rid of Appveyor.
We received a big PR that we struggled to run ourselves from a contributor. We don't have the domain knowledge.
Updating the clients is often tedious busy work. While doing it you think "if we just published our endpoints" this work would be easy.
Things like that have been really problematic, not much of a way around that.
Go client - from GOV.UK PaaS team, really cool but no one knows Go. Until we hear of a need to use Go, we couldn't justify supporting it. Again it comes down to domain knowledge, not a big community around Notify, quite small scale.
Cloudfoundary has only two core client libraries and then the community clients, we don't have that ecosystem where people will actively help out, almost all our clients are Java.
- Java
- Ruby / .NET
- Python
- PHP, Node.js
10% of users are not on the latest versions of the libraries.
Of the 90% most of those are GOV.UK Email, so they're up-to-date since they're a new consumer.
1% of our requests are libraries that are over a year old, lots of them are hitting old endpoints, trying to track down and find old IPs has been really difficult.
How do we make sure that people are aware that new APIs are avaliable, we have not built any warning logs into the current API, for example deprecation headers. How do we make people aware that we want to cut of the last major version of our API?
We still have V1, then we created the V2 endpoints performed better in research, lots of domain language in V1.
Put in a lot of work to move to V2, but lots of people hitting the old endpoints, we may be able to track them down. Send them nice messages.
Services can help us out, never had an issue raised on admin/api repo - terrifying.
Client libraries are small enough so that people feel much more at ease raising issues and pull requests.
We've had maybe 10-15 pull requests, some are documentation tweaks or linting.
To us some work is busy work but to consumers it can be blocking, so they felt empowered to do a pull request.
Really helps on-boarding with clients, can copy code snippets with their api key and send a message in half an hour. With our JWT tokens that we use, I have no confidence that anyone could get that working within a day.
We've had a lot of feedback mostly from Slack, from developers that they've found it easy to use. For smaller teams with less techincal staff, not having to wrestle with another API we can handle that.
Takeaway: Was worth it for us, lots of stumbling blocks but most of them are contained within the dev team.
Make sure there's a serious need for a particular language before you do it.
We could have pushed the less used clients onto the people who need those clients.
[How did you figure out what languages needed clients?]
Started with Python (that's us)
Ruby and Python, but GDS languages.
Node.js I'm not sure about.
Mainly that we've had people asking 'can you support this?', some requests come in for odd user-agents that we don't recognise. Try to trace back from that.
User research has not really flagged this up, since we recruit people that use the integrations that we have.
Started with what GDS uses, and support tickets.
[Have you thought about dropping the clients that have low use, or giving back to community?]
I'd like to push back a bit more. A lot of prioritisation for which client gets updated first. Nothing has been lost yet so far.