You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

The WinBooks on Web Rest API (Application Programming Interface) allows you to access the WinBooks on Web system in a programmatic manner. 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 Ecommerce 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)

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
  • PUT: to create data
  • POST: to update data
  • 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.

  • No labels