logo

Chapps API Help Page

Introduction

The Chapps 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 system.

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

Stakeholders

Three parties are involved while implementing the Chapps API:
  1. The software implementor
  2. The Chapps user
  3. The Chapps 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 API service is done by HTTP (HyperText Transfer Protocol).

Chapps API Configuration

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 API:

Http verbDescription
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.
PUTPUT 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.
DELETEIt 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:

HeaderDescriptionMandatory
AuthorizationContaining the credentials of the software provider (see Authentication for more info).Yes
X-LoginTokenCustom header containing the token of the Chapps user (see Authorization for more info).Yes
AcceptContaining 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 c3Rpam4udmFubmVzdGU6MTIzNDU2

The response headers can contain following properties:

HeaderDescriptionMandatory
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 DescriptionAn explanatory text regarding the status code.No
X-PaginationA 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
Most common http status codes:
CodeDescription
200Standard response for successful HTTP requests.
201The request has been fulfilled and resulted in a new resource being created.
204The server successfully processed the request, but is not returning any content.
400Bad request. The request cannot be fulfilled due to bad syntax.
401Unauthorized. For example when authentication has failed.
403Forbidden. The server understood the request, but is refusing to fulfill it. The reason is provided in the body.
429Too many requests. The user has sent too many requests in a given amount of time.
500Internal server error.
503Service unavailable.

Authentication

The authentication is required to identify the Chapps 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

The API has 6 main objects:
  • Estates
  • Reports
  • ReportContacts
  • ReportDocuments
  • TemplateChecklists
  • Employees
With these objects you can manage a task from start to finish.

Flow

Underneath you will find a typical sequence diagram showing the creation of a task and retrieving the resulting documents.

API Sequence diagram
The same workflow presented in an activity diagram.
API Activity diagram

Methods

A detailed description of the API methods and objects can be found here.

Containing Estate handlers.

APIDescription
GET Api/Estates?page={page}&pageSize={pageSize}

Retrieves estates linked to provided login/business.

GET Api/Estates/{id}

Gets the specified estate.

POST Api/Estates

Inserts a new estate.

PUT Api/Estates/{id}

Updates the specified estate.

DELETE Api/Estates/{id}

Deletes the specified estate.

Containing Report handlers.

APIDescription
GET Api/Reports/{id}?includeMeters={includeMeters}&includeStatistics={includeStatistics}

Gets the specified report.

PUT Api/Reports/{id}

Updates the specified report.

DELETE Api/Reports/{id}

Deletes the specified report.

GET Api/Reports?page={page}&pageSize={pageSize}

Retrieves reports linked to provided login/business.

GET Api/Estates/{estateId}/Reports?page={page}&pageSize={pageSize}

Retrieves reports linked to provided estate.

POST Api/Estates/{estateId}/Reports

Inserts a new report.

Containing ReportContact handlers.

APIDescription
GET Api/Reports/{reportId}/Contacts/{id}

Gets the specified contact.

PUT Api/Reports/{reportId}/Contacts/{id}

Updates the specified contact.

DELETE Api/Reports/{reportId}/Contacts/{id}

Deletes the specified contact.

GET Api/Reports/{reportId}/Contacts

Gets the contacts linked to the provided report.

POST Api/Reports/{reportId}/Contacts

Inserts a new contact.

Containing ReportDocument handlers.

APIDescription
GET Api/Reports/{reportId}/Documents

Gets the documents linked to the provided report.

GET Api/Reports/{reportId}/Documents/{id}

Gets the document linked to the provided report.

APIDescription
GET Api/Templates/Checklists

Retrieves a list of available checklists.

Containing Employee handlers.

APIDescription
GET Api/Employees

Retrieves a list of all active employees within current business.

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:

PropertyDescriptionMandatory
MessageA string holding more detailed information about the occurred error.Yes
ReferenceA reference number which should be provided in case you should contact Chapps support.Yes
TimeStampA datetime of the error.Yes
ModelStateAn 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.