This post details strategies for getting up and running with your chosen API as quickly as possible, and provides tips on uncovering inconsistencies or errors in the API and its documentation, before they become an issue.
As discussed in part 2, I recommended using a pre-existing PHP library when connecting to your target API.
However, it is important to know what your chosen library does and does not do. At the very least, you must know the answers to the following questions, in order to understand your own responsibilities.
Most libraries are primarily about convenience. They enable you to set your authorisation credentials, pass a few values into a method, and transform that information into a well-structured API method call.
What is imperative is that the library has a consistent interface. This is particularly important in terms of how it handles API responses.
If the library responds to a failed call to method A by throwing an exception, it should do the same thing for a failed call to method B. If your chosen library doesn’t exhibit this level of consistency, I advise looking elsewhere.
Before putting code to screen, you should first settle in with your beverage of choice and read the API documentation. Not all the documentation of course, that would be silly (and impractical, in many cases).
Rather, you should read just the documentation required to start using the API. For most APIs this will mean finding out the API endpoints, the method of authentication, and a typical “request” data structure, all of which can usually be found on a “Getting Started” page.
You should also familiarise yourself with the basic process of making an API call using your chosen PHP library.
As ever, the goal is to minimise wasted effort; in this case, by not frittering away your time reading documentation that is quite probably incomplete and inaccurate.
Once you understand the basics of how your target API and chosen library work, you can test specific methods on an as-needed basis, to determine whether they work as documented.
The process is simple. The first time you need to use a method, you should:
Points 1 and 3 are self-explanatory. Point 2 warrants a bit more attention.
The best way to test an API method is in isolation, separate from your add-on code, using hard-coded values.
You need to test two things:
Assuming your chosen PHP library is essentially a “convenience” layer, as described above, it is generally more useful and informative to test the API method directly.
My preferred piece of software for testing API method calls is HTTP Client. It’s simple, cheap, and does its job very well indeed.
HTTP Client allows you to manually construct your API method call, adding POST or GET parameters as required. The data returned by the API method is displayed in a nicely-formatted “response” panel.
If you’re not using a Mac, or just can’t bring yourself to shell out the buck ninety-nine for HTTP Client, there are a number of browser extensions that do a similar job. Just search for “REST Client” in your browser’s extension library, and you’ll find plenty of alternatives. Finally, if you’re a masochist, or have a desperate need to prove your nerd credentials, you can always resort to using cURL in the Terminal.
There are two significant benefits to using a piece of software such as HTTP Client when testing an API method:
The second point is very important. By testing the API method in isolation, you remove ambiguity as to the cause of any issues you encounter. Assuming you’ve entered the request parameters correctly, you can be certain that any anomalies in the response are an issue with the API or its documentation, as opposed to a bug in your code.
Uncovering problems at the “request” stage can be tricky. If the API documentation tells you to send an unknown or badly-formatted parameter to the API, your reward is usually little more than a cryptic error message.
Every single problem I’ve encountered at the request stage of an API call was due to one of the following:
If all of this sounds highly unlikely, allow me to furnish you with two examples:
If you encounter a problem at the request stage, and the API response doesn’t include a meaningful error message, by all means use the above list to identify likely culprits.
However, bear in mind that it’s not your job to debug the API, and you’ll need to confirm any bugs or documentation errors with the API authors before proceeding, so don’t spend too long on this. Just submit a support request, and get on with something more productive.
By comparison, testing the API method’s response is much easier, as discrepancies between the documentation and the actual response are easy to spot. Even so, there are a few things worth looking out for.
The above applies both for successful API calls, and those that generate an error. As ever, if you find a anomaly, confirm the intended behaviour with the API author before proceeding.
Follow the strategies outlined in this post to get up-and-running with your chosen API quickly, and uncover potential stumbling blocks before they become an issue.
In the next post, I’ll be talking testing.