Skip to main content

How to define a REST service with pagination support

Part 1: http://vunvulearadu.blogspot.ro/2014/08/how-to-define-rest-service-with.html
Part 2: http://vunvulearadu.blogspot.ro/2014/08/how-to-define-rest-service-with_17.html

In this blog we will talk about REST API and pagination. Almost all services that are now created are exposed in REST format. This format give us the possibility to expose an endpoint that can be consumed by numerous devices and platforms from laptops to tables and phones.
There are different ways to expose a collection of items using pagination. In the next part I will present a mechanism to expose collection of items using pagination in REST.

Request

A new page request in REST format is pretty simple when we talk about pagination. We need to crucial information for such a requests – page number and page size. Because we request content it is obviously that we will use the GET method.
When we send a request using GET, all request information should be in the URL. We can end up with following possibilities:
GET /api/cars?pageNumber=3&pageSize=20
GET /api/cars/20/3
Both version of request can be good. I would say that the first version is better because is clear for clients what each parameter represents. In the second version is not clear what 20 and 3 represents.

Response

The request was the simplest thing. The response is more complicated and there are different opinions about how the response should look like.
It is pretty obvious that a response should contain:

  • List of items
  • Page number
  • Page size

Additional to this we should have:

  • Total items count
  • Total pages count

Of course if we know total items count it is simple to calculate the number of pages, but it is simpler to calculate this number on the server side and send this value to our clients. They will not need to implement the same calculation again and again.
When we expose a REST service, we need to expose all the content that is needed by client to use and navigate in our REST services without having to compute or calculate anything. They should be able to ‘auto discover’ all the features that are available.
Because of this each response should contain URL links that would allow clients to navigate between pages:

  • Next page link
  • Previous page link
  • First page link
  • Last page link

There are people that would say that this is duplicate information, because clients can generate this URL, but a true rest service should expose all the links between resources. It is simpler for clients to navigate between resources in this way. Also we reduce the risk of errors on client’s side.
Response content:
{  
   "pageNumber":1,
   "pageSize":20,
   "totalPages":3,
   "totalItemsCount":46,
   "prevPageLink":"",
   "nextPageLink":"/api/car?page=2&pageSize=20",
   "firstPageLink":"/api/car?page=1&pageSize=20",
   "lastPageLink":"/api/car?page=2&pageSize=20",
   "items":[
                    ...
 ]
}
In the above example we can see that all the information can be found in the content of the response. As we can see, the prevPageLink is empty. The empty string is used when that resource don’t exist. For example when we are on the first page, we cannot have a previous page.
Another possibility is to put all the meta information  related to page in the response heather. In this case the content of the response will have only the array of items. For this we need to create a custom heather where we should add all this information.
Response heather:
{
   "pageNumber":1,
   "pageSize":20,
   "totalPages":3,
   "totalItemsCount":46,
   "prevPageLink":"",
   "nextPageLink":"/api/car?page=2&pageSize=20",
   "firstPageLink":"/api/car?page=1&pageSize=20",
   "lastPageLink":"/api/car?page=2&pageSize=20",
}
Response content:
{
 [
  { item1 }
  { item2 }
                    ...
 ]
}
As we can see second option is cleaner. We have in the response content the list of items without any meta-data related to pagination. This is the solution that I prefer to use.
The downside of this solution is at debug and discovery level, when clients’ needs to access pagination information from heather. To do this they need to write additional code, that can add complexity to the application. Also, if we want to make a request from a browser to see the response, we will not be able to see all the response directly in the browser. We will need a ‘developer’ tool/plugin to access the response heather.
The first solution is extremely clear and easy to use. Even I prefer the second solution, in production we ended up with the first one.

Error codes

The last think that I would like to talk about is error codes. I don’t what to go over each error code that we should return and manage. What we should take into account is the standards HTTP error code. For error that we have in our backend we should use standard HTTP error codes – we should never invent our own error codes or map standard error codes to scenarios where that error codes don’t apply.
Why? Because web developers are used to specifies error codes for different scenarios. We should respect the existing standard, not create a new one.
For example, when the request is invalid (for example the page number is missing) we should return 204 – No Content.
In this blog post we saw different ways how to implement pagination support in our REST services. In the next blog post we will see how we can implement such a service using API Controller and Azure Web Sites.

Part 1: http://vunvulearadu.blogspot.ro/2014/08/how-to-define-rest-service-with.html
Part 2: http://vunvulearadu.blogspot.ro/2014/08/how-to-define-rest-service-with_17.html

Comments

Popular posts from this blog

How to check in AngularJS if a service was register or not

There are cases when you need to check in a service or a controller was register in AngularJS.
For example a valid use case is when you have the same implementation running on multiple application. In this case, you may want to intercept the HTTP provider and add a custom step there. This step don’t needs to run on all the application, only in the one where the service exist and register.
A solution for this case would be to have a flag in the configuration that specify this. In the core you would have an IF that would check the value of this flag.
Another solution is to check if a specific service was register in AngularJS or not. If the service was register that you would execute your own logic.
To check if a service was register or not in AngularJS container you need to call the ‘has’ method of ‘inhector’. It will return TRUE if the service was register.
if ($injector.has('httpInterceptorService')) { $httpProvider.interceptors.push('httpInterceptorService&#…

ADO.NET provider with invariant name 'System.Data.SqlClient' could not be loaded

Today blog post will be started with the following error when running DB tests on the CI machine:
threw exception: System.InvalidOperationException: The Entity Framework provider type 'System.Data.Entity.SqlServer.SqlProviderServices, EntityFramework.SqlServer' registered in the application config file for the ADO.NET provider with invariant name 'System.Data.SqlClient' could not be loaded. Make sure that the assembly-qualified name is used and that the assembly is available to the running application. See http://go.microsoft.com/fwlink/?LinkId=260882 for more information. at System.Data.Entity.Infrastructure.DependencyResolution.ProviderServicesFactory.GetInstance(String providerTypeName, String providerInvariantName) This error happened only on the Continuous Integration machine. On the devs machines, everything has fine. The classic problem – on my machine it’s working. The CI has the following configuration:

TeamCity.NET 4.51EF 6.0.2VS2013
It seems that there …

[Post-Event] Codecamp Conference Cluj-Napoca - Nov 19, 2016

Last day I was invited to another Codecamp Conference, that took place in Cluj-Napoca. Like other Codecamp Conferences, the event was very big, with more than 1.000 participants and 70 sessions. There were 10 tracks in parallel, so it was pretty hard to decide at  what session you want to join.
It was great to join this conference and I hope that you discovered something new during the conference.
At this event I talked about Azure IoT Hub and how we can use it to connect devices from the field. I had a lot of demos using Raspberry PI 3 and Simplelink SensorTag. Most of the samples were written in C++ and Node.JS and people were impressed that even if we are using Microsoft technologies, we are not limited to C# and .NET. World and Microsoft are changing so fast. Just looking and Azure IoT Hub and new features that were launched and I'm pressed (Jobs, Methods, Device Twin).
On backend my demos covered Stream Analytics, Event Hub, Azure Object Storage and DocumentDB.

Title:
What abo…