Chapps Rental API - Help Page

Introduction

The Chapps Rental API (Application Programming Interface) documentation specifies how software can interact with Chapps.

This document lists the remote calls exposed to the API consumers and more in detail shows the used protocols and all the available data structures that can be passed around.

The API is the third interface of the Chapps Rental environment.

1. Chapps Rental Service: This interface enables the Chapps Rental app, located on the iPad or Android tablet, to communicate with the service. This is a non public service.
2. Chapps Rental Manager: This web interface enables the Chapps user to manage the reports, their agenda and modify templates.
3. Chapps Rental API: This interface enables a company to synchronize or manage the inspection jobs, reports or their agenda via a third party software.

Stakeholders

Three parties are involved while implementing the Chapps Rental API:

1. The software implementor
2. The Chapps user
3. The Chapps Rental API service

The software implementor creates the link for one or multiple Chapps users. This document is focused on the software implementor.

Configuration

Protocol

The way the messages are transported between client and Chapps Rental API service is done by HTTP (HyperText Transfer Protocol).



The HTTP message has three major parts:

1. The method (or HTTP verb) being GET, POST, PUT, DELETE,... These verbs corresponds to the kind of operation that is requested.
2. The headers containing all the meta data. For example: authentication, paging, requested output format,...
3. The content holding in case of a request, the data to handle or in case of a response, the requested data.

Http methods

These verbs are implemented in the Chapps Rental API:

Http verb	Description
GET	The HTTP GET method is used to retrieve a representation of a resource. In the non-error path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). According to the design of the HTTP specification, GET requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
POST	The POST verb is utilized for creation of new resources. On successful creation it will return a Location header with a link to the newly-created resource with the 201 HTTP status. POST is neither safe nor idempotent.Making two identical POST requests will result in two resources containing the same information.
PUT	PUT is utilized for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful update, this method returns 200 (or 204 if not returning any content in the body). PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call.
DELETE	It is used to delete a resource identified by a URI. On successful deletion a Http status code 200 (OK) or 204 (NO CONTENT) is provided. If a the resource to delete does not exist, a 404 (NOT FOUND) is returned. Therefore, this implementation of the DELETE operation is not idempotent.

Headers

Here we will make a distinction between the request and the response headers.

The request headers should/can contain following properties:

Header	Description	Mandatory
Authorization	Containing the credentials of the software provider (see Authentication for more info).	Yes
X-LoginToken	Custom header containing the token of the Chapps user (see Authorization for more info).	Yes
Accept	Containing the format in which the response should be structured. Two formats are supported: application/xml: Returns an XML representation of the resource. application/json: Returns a JSON representation of the resource. If not provided, an invalid accept header or multiple accept headers are provided, the return defaults to application/json.	No

Request header example:

GET https://rental.chapps.com/api/estates?page=0&pagesize=1 HTTP/1.1
X-LoginToken: 210023059172120152175178125175045218002028013194157253064128016124170196227194015149201207234021
Accept: application/json; version=1
Authorization: Basic ZXhhbXBsZToxMjM0NTY=

The response headers can contain following properties:

Header	Description	Mandatory
Http status Code	A code indicating the status of the handling of the request (see list of most common http status codes).	Yes
Http status Description	An explanatory text regarding the status code.	No
X-Pagination	A json object containing a JSON object holding paging information (see Advanced for more info).	No

Response header example:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
X-Pagination: {"TotalCount":215,"TotalPages":3,"PrevPageLink":"","NextPageLink":"https://rental.chapps.com/Api/Estates?page=1&pageSize=100"}
Date: Mon, 07 Jul 2014 14:00:45 GMT
Content-Length: 217

Code	Description
200	Standard response for successful HTTP requests.
201	The request has been fulfilled and resulted in a new resource being created.
204	The server successfully processed the request, but is not returning any content.
400	Bad request. The request cannot be fulfilled due to bad syntax.
401	Unauthorized. For example when authentication has failed.
403	Forbidden. The server understood the request, but is refusing to fulfill it. The reason is provided in the body.
429	Too many requests. The user has sent too many requests in a given amount of time.
500	Internal server error.
503	Service unavailable.

Authentication

The authentication is required to identify the Chapps Rental API client. This client can be created by a software implementor, representing its interface to one or multiple Chapps users. The relationship between Software implementor and Chappsuser can be a one-to-one link. Even in that case it is required be authenticated as software provider.
The authentication of the client is performed by so called "Basic authentication". The HTTP header "Authorization" is used, with the property value starting with "Basic" followed by a space and the base64encoded string of {username}:{password}.
Since the credentials are not encrypted all methods are done by HTTPS (HyperText Transfer Protocol Secure).

Authorization

The authorization of the Chapps user is done by a custom Header named: X-LoginToken. This header contains a string representing the Chapps user for which the HTTP action will be performed. An authenticated software provider can send requests on behalf of multiple Chapps users.
Example: X-LoginToken: 210023059172120152175178125175045218002028013194157253064128016124170196227194015149201207234021

API

• Estates
• EstateGroups
• Offices
• Reports
• ReportContacts
• ReportDocuments
• TemplateChecklists
• Employees
• Webhooks
• WebhookResults
• ExtendedReports

Methods

Error handling

In case the response header returns a status code other than 2xx, an error has occurred. In this case an object is returned in the body holding these properties:

Property	Description	Mandatory
Message	A string holding more detailed information about the occurred error.	Yes
Reference	A reference number which should be provided in case you should contact Chapps support.	Yes
TimeStamp	A datetime of the error.	Yes
ModelState	An object containing detailed information in case a validation error occurred.	No

The object will be presented in XML or JSON according to the Accept header of the request.

Example in JSON:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Date: Tue, 23 Sep 2014 12:21:17 GMT
Content-Length: 1603
{
    "Message":"The request is invalid. See ModelState for more information.",
    "Reference":12177,
    "TimeStamp":"2014-09-23T14:21:15.9186264+02:00",
    "ModelState":
        {
            "estateModel.Address.Country":["AddressV1Model.Country 'XX' is invalid."]
        }
}

Example in XML:

HTTP/1.1 404 Not Found
Content-Type: application/xml; charset=utf-8
Date: Tue, 23 Sep 2014 12:27:47 GMT
Content-Length: 2205
<error>
    <message>ChappReportException: The report with Id '14892' does not exist.</message>
    <reference>12181</reference>
    <timestamp>2014-09-23T14:27:47.0876264+02:00</timestamp>
</error>
                

Advanced

Pagination

While retrieving possiblly large lists (for example estates or reports), a pagination mechanism is implemented. Therefore it is possible that not all results are returned. In that case you will find a X_Pagination argument in the http header.
This header is always represented as JSON and contains following properties:

• TotalCount
• TotalPages
• PrevPageLink
• NextPageLink

The properties are self explanatory and make it possible to navigate through the result pages via PrevPageLink and NextpageLink. You can override the maximum returned results by adding these arguments to the query string:

• page
• pagesize

The page argument is zero based.

example of request querystring:

https://rental.chapps.com/api/estates?page=0&pagesize=100

example of response X-Pagination header :

X-Pagination: 
{
    "TotalCount":215,
    "TotalPages":3,
    "PrevPageLink":"",
    "NextPageLink":"https://rental.chapps.com/Api/Estates?page=1&pageSize=100"
}
        

Throttling

The API throttling is a system with bursting capabilities and built-in protection against thread starvation issues.
In order to ensure the availability of the service the activities of each client is monitored and if it exceeds predefined parameters, the client will be unable to perform any succesfull requests during an arbitrary period. The parameters can be altered without notice to the clients.

Current parameters:

• maximum requests per second: 20
• maximum requests per minute: 240

If by any means, these parameters would be to restrictive, please contact us at info@chapps.com.