Daniel Watrous on Software Engineering

A Collection of Software Problems and Solutions

Posts tagged documentation

Software Engineering

Software licensing: RESTful API, resources vs. parameters

I’m starting to build out the RESTful API for the software licensing system. The first api call to implement is this


That came from the initial design documents and implicitly suggests that there is a difference between the resource and parameters passed in when asking for the resource.

This distinction is important and came up today when I was thinking about pagination. As the API is defined currently, the above URI would return all site licenses associated with an apikey. The first thought that came to mind was that the number of licenses could be very large and so there needs to be some way to paginate the results.

Difference between resource and parameters

The pagination itself shouldn’t be too difficult. However, I wanted to be sure that the API calls made sense and would be intuitive. That brought me to this discussion about pagination in a REST web application. What I take away from that post is that it’s fine to mix query string parameters with RESTful identification of a web resource. That wasn’t clear to me before.

One helpful tip given in one of the comments was to look at the Twitter API. I did have a look and I do agree that it’s very clean. They have a clean and clear style of documenting the API and the structure of their RESTful calls, which includes both identification of resources and parameters to paginate, limit or otherwise clarify aspects of that resource.

Structuring my API so that it clearly identifies resources and accepts parameters in a query string in the URI is how I’ll approach development for the current software licensing plugin going forward.