In this part of the REST API Library series we will create the order API based on DAWs order entry sample database.

We will take a look at additional features such as paging, selections as well as additional features to schemas/models.

to get started lets create the order api controller by adding a new http handler based on the cszWebAPIController class.

 

Next we will define our schema/model for the API.

 We are definfing a schema called order. This is our main schema and contains the  order header fields as well as a parent schema for customer. We also added a child schema for the detail lines as well.

In addition we are declaring a second schema called ‘orderlist’ which we will use to demonstrate using multiple schemas in an API controller.

Now lets declare our standard GET route to return a list of orders

 

just like the inventory example we simply declare a GET route with the default WebAPI_Get method, summary and description info for the API documentation.

We also define the response

A test of the new API returns all orders in a json array. This can lead to a lot of data of course.

In order to limit the amount of data returned we want to add paging functionality. The REST library supports required and optional paging and the paging settings can be made for each controller as well as for each path.

to enable paging we can add the following code to our controller

This line will set the controllers paging default to required with a maximum of 50 records per page and a default of 20.

this will make 3 changes to the API.

first the output will automatically be governed by the paging settings.

second on the input side we can now supply the following query parameters

  • page
    the current page to be returned
  • pageSize
    number of rows to return. this cannot be greater than the maximum page size defined on the controller or route

ad last but not least the return data will include a X-Pagination http header containing the information on the page returned.

The X-Pagination header contains a json object with the following fields

  • PageSize
  • CurrentPage
  • TotalCount (not with embedded db)
  • TotalPages (not with embedded db)

the X-Pagination header can be used by the calling program.

In addition to paging we want to be able to sort the orders by different sort orders. We need to declare these so we can allow the client to set the sort order

lets add the following to our route delcaration

this will declare 3 different sort orders, by order number, order date as well as customer. The first two allow descending orders as well.

And last we set the default sort order to order number.

this now enables the client to send two additional query parameters

  • order
  • desc

for example

/api/v1/order?order=orderDate&desc=true

or with paging

/api/v1/order?order=orderDate&desc=true&page=10

Of course we also need to be able to select orders for example by date. Lets add some functionality to do just that.

First we modify the orderheader datadictionary to add the constraint logic

now we add a new method for our order API

this new method gets the url parameters ‘dateFrom’ and ‘dateTo’ and uses these values to initialize the DDs constraints

then we simply call the original GET API to get the data and then clear the constraints

we need to modify the route declaration to call this new method

this will now allow the user of the API to specify the dateFrom and dateTo parameters to constrain the orders returned.

Of course all these changes are also made to the OpenAPI documentation as well

Now as a last feature lets see how we can use a second schema in the same API to return the same dataset with a different schema

All we need to do is to declare a new route as follows

as you can see in this route we are calling the same WebAPI_GET method but we are  specifying a different schema called “orderlist”.

this will return the same dataset but with a much smaller number of fields.

In the following posts in this series we will look into detailed features such as authentication and more.

 

 

Michael Salzlechner is the CEO of StarZen Technologies, Inc.

He was part of the Windows Team at Data Access Worldwide that created the DataFlex for Windows Product before joining StarZen Technologies. StarZen Technologies provides consulting services as well as custom Application development and third party products