We have used Royal Mail for postage for some time. They had an XML API which we have used, and it works.
What is interesting is how all of these APIs are moving from XML to JSON now. One of the big benefits of JSON is none of the FUCKING XML NAMESPACES (sorry, did I say that out loud?).
Even so JSON has its issues, but nothing like XML with namespaces.
They have a web site with a login and loads of interactive stuff, and that includes the API and API manuals. They also have a "V4 Shipping API Consolidated Guide" PDF they sent. So how hard could it be. I had two manuals!
To put this in context, I am someone that has used (and written) many APIs that are JSON/http based over the years. I practically invented the concept (I even have a patent on form posting from over 30 years ago). I have some clue, honest.
I actually quite like the latest "web" based stuff with JSON sent and received. Even OAUTH crap. I have some experience with this, honest.
Update: Before logging in there are some extra links, and another set of manuals, which is yet again different and contradictory - arrrg!
First challenge is authentication, and to some extent the manuals were not that bad. The one critical thing they could have done is include, in any of the manuals, one simple example.
They use OAUTH2 but in a way I have not seen anyone else use. I needed a POST to a URL with a URL encoding post of grant_type=client_credentials (and it had to be a POST not a GET) using Basic authentication of the client ID and key they allocated. This is an unusual way to OAUTH2, but valid, to my huge delay of some hours getting the hang of it was really down to me. I get back a Bearer key with expiry (1 hour).
One issue is the URL, well, the hostname. The documents state that the hostname to use is for their TEST system. This is good, they have a test system, but the other manual suggests it is the hostname for the LIVE system. Why?
I eventually worked it out, there is one hostname for authentication, and whether it is test or live depends on your account. Your account can be in "sandbox". I mean that is great, a good system, but why the fuck not state that in either of the manuals?
What adds to the fun is that hostname is actually only to authenticate. The actual hostname for the service is different, and searching both manuals I do not see the actual hostname for actual API calls listed anywhere.
The big clue was some swagger.json file you can download. Loads of JSON, some "OpenAPI" thing. That has been way more helpful than either of the manuals!
It explains the actual hostname to use for the API, and each of the schemas for each API.
The manual, well one of them, lists fields you need, but omits that these may or may not be in sub objects. The JSON blob explains in way more detail.
And, of course, this JSON file, whilst really good, is missing a load of things, like creating manifests!
For example, the error "Could not find member 'ContactName' on object of type 'Destination'. Path 'Destination.ContactName'" fooled me for a while as I was supplying Destination.ContactName. What it meant is I should not be supplying that. I read "Count not find" as I was missing something, but no, it meant I had supplied something it "could not find" a use for. That is shit UI. (FYI I should have provided Destination.Address.ContactName)
There is, of course, tracking. There is an API to get tracking and an option to have tracking posted to a web hook - yay!
But the documentation for the tracking API just says the response is a tracking number? Which, err, makes no sense, what of the status of the shipment. Hmmm.
And apparently the tracking web hook is not supported, so why the hell is it in the API documentation? Arrrg!
I have it working now - but this is literally one of the worst documented APIs ever.
The raw JSON file was more documentation than either if the manuals, but even that is missing bits.
Icing on the cake
Royal Mail have What3Words embedded. I kid you not.
This is so mental! RM have PAF which has detailed (like, to 10cm) delivery point details on all UK addresses. They are the one organisation that has ZERO use for W3W.
I don't know what they do with it - I will ask?
- If a W3W supplied is way off, like hundreds of miles, do you use it?
- If a W3W is next door to postal address provided, do you use it?
- If a W3W is within target address, e.g. a shed in garden, do you use it?
If all are "no", I have to ask WHY THE FUCK it exists in their API!
[Update: Answer is they don't use the W3W filed.... So WTF have it?!?!]