A RESTful Webservice

The Multivers and Boekhoud Gemak WebAPI is a RESTful webservice. This document will give some insight into how a RESTful webservice works and how an application can communicate with it.

What is a RESTful webservice

A RESTful webservice is a service that is using the HTTP protocol to exchange resources. Below are a few keypoints about a RESTful service.

Everything exchanged by the service is a resource
Every resource has to have its own address
Resources have to be accessible by a uniform interface
Multiple formats can be used for communications. Multivers and Boekhoud Gemak WebAPI supports both JSON and XML. More information about these formats can be found here.

HTTP methods

A RESTful webservice makes use of the HTTP methods to handle CRUD Operations. Every CRUD operation is executed with a different HTTP method. The following list contains the HTTP methods used to perform these operations with an example of what the call must look like. All examples are based on the customer object.

GET
The GET method is used to retrieve data from the API. The call returns either a list of objects or 1 stand alone object.


    GET http://localhost/api/MVL00001/Customer/1001 HTTP/1.1
    Accept: application/json
    Authorization: Bearer [accesstoken]
    Host: lokalegastheer

POST
The POST method creates new objects based on the data given in the request body. The data in the request body should contain all properties of the object. The properties that are missing will be given its default value.


    POST http://localhost/api/MVL00001/Customer HTTP/1.1
    Accept: application/json
    Authorization: Bearer [accesstoken]
    Content-Type: application/json
    Host: lokalegastheer
    Content-Length: 1318
    Expect: 100-continue

    {
        "ApplyOrderSurcharge":false,
        "ChargeVatTypeId":"J",
        "CollectiveInvoiceSystemId":null,
        "CombineInvoicesForElectronicBanking":false,
        "CreditLimit":0.0,
        "CreditSqueezeId":null,
        "CurrencyId":null,
        "CustomerGroupId":0,
        "CustomerStateId":null,
        "Database":null,
        "DeliveryConditionId":null,
        "DiscountPercentage":0.0,
        "HasOutstandingBalance":false,
        "IncludeUnpaidInvoices":false,
        "IntrastatGoodsCodeId":null,
        "IntrastatGoodsDistributionId":null,
        "IntrastatStatSystemId":null,
        "IntrastatTrafficRegionId":null,
        "IntrastatTransactionTypeId":null,
        "IntrastatTransportTypeId":null,
        "InvoiceOnBehalfOfMembers":false,
        "IsDunForPayment":false,
        "IsInFactoring":false,
        "IsPaymentRefRequired":false,
        "PaymentConditionId":null,
        "Person":null,
        "PricelistId":null,
        "PrintPurchaseDetails":false,
        "PurchaseOrganizationId":null
        "RevenueAccountId":null,
        "VatScenarioId":null,
        "AccountManagerId":null,
        "Addresses":null,
        "BusinessNumber":null,
        "City":"UTRECHT",
        "CocCity":null,
        "CocDate":null,
        "CocRegistration":null,
        "CountryId":null,
        "CustomerId":"",
        "Email":"info@bekkerem.nl",
        "Fax":null,
        "Homepage":"www.bekkerem.nl",
        "LanguageId":null,
        "MobilePhone":"06-24367542",
        "Name":"Van Bekkerem B.V.",
        "OrganizationId":0,
        "ShortName":"BEKKEREM",
        "Street1":null,
        "Street2":"Lorenzkade 39a",
        "SupplierId":null,
        "Telephone":"078-6230230",
        "VatNumber":null,
        "VatVerificationDate":null,
        "ZipCode":"2369 WE"
    }

PUT
The PUT method is used to edit data from the API. The data in the request body should contain all properties of the object. The properties that are missing will be given its default value.


    PUT http://localhost/api/MVL00001/Customer/1001 HTTP/1.1
    Accept: application/json
    Authorization: Bearer [accesstoken]
    Content-Type: application/json
    Host: lokalegastheer
    Content-Length: 1389
    Expect: 100-continue

    {
        "ApplyOrderSurcharge":true,
        "ChargeVatTypeId":"J",
        "CollectiveInvoiceSystemId":"0",
        "CombineInvoicesForElectronicBanking":true,
        "CreditLimit":1000000.0,
        "CreditSqueezeId":"0",
        "CurrencyId":"",
        "CustomerGroupId":0,
        "CustomerStateId":"A",
        "Database":"",
        "DeliveryConditionId":"V",
        "DiscountPercentage":0.0,
        "HasOutstandingBalance":true,
        "IncludeUnpaidInvoices":false,
        "IntrastatGoodsCodeId":null,
        "IntrastatGoodsDistributionId":null,
        "IntrastatStatSystemId":null,
        "IntrastatTrafficRegionId":null,
        "IntrastatTransactionTypeId":"",
        "IntrastatTransportTypeId":null,
        "InvoiceOnBehalfOfMembers":false,
        "IsDunForPayment":true,
        "IsInFactoring":true,
        "IsPaymentRefRequired":false,
        "PaymentConditionId":"INC",
        "Person":"de heer J.A.M. van Bekkerem",
        "PricelistId":"",
        "PrintPurchaseDetails":false,
        "PurchaseOrganizationId":"",
        "RevenueAccountId":"",
        "VatScenarioId":null,
        "AccountManagerId":"KK",
        "Addresses":[],
        "BusinessNumber":"",
        "City":"SLIEDRECHT",
        "CocCity":"DORDRECHT",
        "CocDate":"3/28/2012",
        "CocRegistration":"32456",
        "CountryId":"",
        "CustomerId":"1001",
        "Email":"info@bekkerem.nl",
        "Fax":"078-6230231",
        "Homepage":"www.bekkerem.nl",
        "LanguageId":"",
        "MobilePhone":"06-24367542",
        "Name":"Van Bekkerem B.V.",
        "OrganizationId":25,
        "ShortName":"BEKKEREM",
        "Street1":"Handelsmaatschappij",
        "Street2":"Lorenzkade 39a",
        "SupplierId":"",
        "Telephone":"078-6230230",
        "VatNumber":"NL123456782B01",
        "VatVerificationDate":"7/28/2000",
        "ZipCode":"2369 WE"
    }

DELETE
Remove an instance of the object.


    DELETE http://lokalegastheer/API_1_2_0/api/MVL00001/Customer/1053 HTTP/1.1
    Accept: application/json
    Authorization: Bearer [accesstoken]
    Host: lokalegastheer

Result types

The following kinds of results are available within the WebAPI.

Editable objects
All CRUD operations can be executed on these objects.

Info objects
Info objects contain the most important information of the object. These objects are read only so there are only GET methods available.

Lists
Lists can contain either multiple editable or info objects. Only GET methods are available.

Name value lists
Name value lists contain pairs of names and values. These are great when you want to show a list of names without any overhead. Only GET methods are available.

Response codes

Every response to an API call has an HTTP status code. The most common ones are described below.

200: OK
Everything went fine. The response body will contain a result depending on the request type.

400: BAD REQUEST
Not all required parameters are given.

401: UNAUTHORIZED
The user is not logged in or no database is given.

404: NOT FOUND
Either the call that is being made does not exist or the id of the given object does not exist.

How is the data of users protected

A user will need to authorize an application to make use of his or her data through the webAPI. This is done through the oAuth 2.0 protocol.