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 …

Run native .NET application in Docker (.NET Framework 4.6.2)

Scope
The main scope of this post is to see how we can run a legacy application written in .NET Framework in Docker.

Context
First of all, let’s define what is a legacy application in our context. By a legacy application we understand an application that runs .NET Framework 3.5 or higher in a production environment where we don’t have any more the people or documentation that would help us to understand what is happening behind the scene.
In this scenarios, you might want to migrate the current solution from a standard environment to Docker. There are many advantages for such a migration, like:

Continuous DeploymentTestingIsolationSecurity at container levelVersioning ControlEnvironment Standardization
Until now, we didn’t had the possibility to run a .NET application in Docker. With .NET Core, there was support for .NET Core in Docker, but migration from a full .NET framework to .NET Core can be costly and even impossible. Not only because of lack of features, but also because once you…