Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The WinBooks on Web Rest API (Application Programming Interface) allows to access the WinBooks on Web system from an external application. That means you can write code to access almost everything within your WinBooks on Web folders. This allows for 3rd party application integration. For example, you could create an application that syncs your WinBooks on Web data with your E-Commerce system.

Some basic facts of the WinBooks on Web API:

  1. RESTful API.
  2. Supports JSON
  3. HTTP authentication through OAuth20 (read this document to learn how to generate an Exchange Key)

.NET developers

While you can query, insert and delete every data of your folders directly through HTTP request / XML or JSON, WinBooks on Web provides an assembly for .NET developers allowing them to do that more easily.

You can download this assembly (the Winbooks.Apis.Services), and an example of Windows console application using it (Winbooks.Apis.Demo):

Authentication 

When an end-user wants to access data on WinBooks on Web, they have to provide a user code and password for authentication purposes. WinBooks on Web will grant them access to some data of their folders and to some functions of the application depending on their profile.

The same concept applies to an application that wants to access some data on WinBooks on Web. The application has to authenticate itself to WinBooks on Web. To do that, we use OAuth20 security standard, an extremely strong and widely used authentication method. It's the same system which is used to access Google's API.

Through the application, the end-user can generate a "key" called an exchange token with which the external application will be able to access the data of WinBooks on Web that the end-user can access themselves.
At any time, the end-user can revoke the access to the external application by simply deleting the exchange token.

Usage of REST in the WinBooks on Web API

Basic methods and URL structure

Depending on whether we are addressing single entity or plural entities, the development or production URL structure looks like this:

  • URL for single entity:
    • Formula: { REST API Host } / app / { Winbooks OM } / { Code } / Folder / { FolderCode }
    • Example:  https://rapi.winbooksonweb.be / app / Customer SARA Folder PARFIWEB_DEMO
  • URLS for plural entities:
    • Formula:  { REST API Host } / app / { Winbooks OMS } Folder { FolderCode } 
    • Example:  https://rapi.winbooksonweb.be / app / Customers  Folder PARFIWEB_DEMO

The methods are using the basic verbs: 

  • GET: to retrieve data (entities or projections).
  • POST: to insert or update entities. 
    • If the Id's are not specified, POST will create new Id's. 
    • If the Id's are specified but do not exist, it will create the entities with these Id's.
    • if the Id's are specified and already exist, it will update the entities.
  • PUT: to update entities with specified Id's. If the Id's do not exist, it's raising an error.
  • DELETE: to delete data

Handling errors

Similar to requests, there are two main components of a RESTful response: the response body, and a status code. Errors are identified by HTTP status codes like:

  • 200: OK - the request is successful
  • 201: CREATED - the created action is successful. It's used to confirm the PUT or POST request.
  • 400: BAD REQUEST - the request is invalid. This happens when the data is not validated, or it is in the wrong format. It often happens for POST and PUT requests.
  • 401: UNAUTHORISED - the request is not authorized. You need to be authorized to be able to access the resource.
  • 404: NOT FOUND - the resource could not be found. It happens when the URL has no corresponding resource.
  • 405: METHOD NOT ALLOWED - the method is not supported for the request.
  • 409: CONFLICT - the request tries to create a duplicated entity.
  • 500: INTERNAL SERVER ERROR - this is the general message for all errors. It can be due to various different circumstances.

**All status codes being prefixed by "2" are successful status codes. All other prefixes mean error. When receiving an error status code, the client could read the content of the response to get more details.

Outputting JSON or XML

By default, the API returns standard structured JSON.