We knew that, if the app were to be a success, then it would increase the load on the servers since a lot of the logic in the app uses the Givey API. The API at the time (V3) was just a simple REST api with relational data bundled in to the same response.
You would make a request to get a charity and it would return the serialized charity information as well as serialized information regarding any of the relations on the charity object. This was very convenient, 1 request to get all the information you need.
The problem was that this request could be very slow. One request to that API endpoint would be fine, but consider 100’s of requests to that endpoint, triggered at the same time. That is when things go bad.
So I decided it was time for a new API version. This would be the second API version I have written for Givey since I co-wrote V3 back in 2014.
While looking through the code for V3 and pinpointing strengths and weaknesses, I discovered that it wasn’t too consistent in the way that data was returned and presented. I knew I needed a schema to follow. Something that someone could look at or be pointed to the schema docs and know exactly how to pull and read the data.
I decided to go with JSON API. This meant that everything was consistent and predictable.
While building the API, I knew there was no point in building every endpoint that V3 had. After all, this version of the API would not be public (publicly accessible but not publicly advertised). With that in mind, I wrote the endpoints that I knew the app would need to use. This made it so that I could get all of the API work done at a quicker pace and then move on to the app.
Since I was using JSON API, I utilised some of the features that I will quickly go over:
By simply specifying which fields to pull in the URL parameters, we can return only the data that the requester wants. This means no more twitter handle returned for charities, unless you need it. Doing so speeds up the request time and makes parsing the request a lot easier.
A fields request looks like:
The above request will only return the name of each charity, and the name of each owner. By default, relations such as the owner aren’t included. That is where the next feature comes in to play:
If I were to request the data for a charity, I would need to make another request to get the owner of that charity (using the charity ID). This isn’t ideal since 2 requests are needed to get the information that I want.
So, in V4, you simply specify which relations you want to include:
The above request would return the owners for each charity.
In V3, access tokens were specified in the URL. The problem with this is that someone may want to share an API endpoint they have been using, but accidentally keep their access token in the URL that they share.
In V4, access tokens in the URL is still a thing, but we prefer (and document) the better method of using an authorization header in the request.
With the new version of the API now done (as much as was needed for the app), it was time to start building the app.
You can download the Givey app for FREE for Android and IOS: