In this series of articles I’m going to take a closer look using sample code which I will explain in detail to illustrate the concepts. The code used in each article will be made available in full for you to download and run.
So, let’s get started! Here is a simplified PHP script:
If you were following the comments, you’ll know this code does the following:
Two of the core concepts of Web Services are at the heart of this example: authentication and communication.
Let’s start with the communication aspect and our first acronym: REST.
What is REST? REST, or REpresentational State Transfer, is an architectural style, but when applied to a Web Service, it refers to a communication protocol that:
Looking at this in relation to our example:
fetchall make HTTP requests. Getting the folder listing is done as a
GETrequest. Adding a document is done using a
$folderContentEndPointUristring that I used was the following URI:
kind) were passed as a JSON object.
/api/and finding the appropriate related resource via hypertext links. This is not explicitly shown in the example above.
As a result of this, the BC Web Services API can be referred to as RESTful, that is, they implement a RESTful communication protocol.
So, on to the authentication.
The first, somewhat involved, step of the sample code was to authenticate with BC. This was done by using the OAuth protocol.
But what is OAuth?
The Abstract for the OAuth 1.0 Protocol from the Internet Engineering Task Force (IETF) sums it up nicely as follows:
OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end-user). It also provides a process for end-users to authorize third-party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.
OAuth is widely used as a result of this.
RFC 5849, which defines OAuth 1.0a, describes a nice scenario in which the OAuth protocol enables a resource owner (Jane) to give access to some protected resources (photos) on a server she uses to another client website (a printer).
In article 3 of this series we will go into a more detailed example, explicitly highlighting the URLs BC provides to enable the 3 step authentication process and HTTP header information showing exactly what needs to be sent to BC.
For those familiar with OAuth, you will wondering what version of OAuth we are using.
BC, starting with BC 6.1, supports version 1.0 of OAuth, but a number of features from OAuth 1.0a have been added, such as support for the oauth_callback parameter which is included in BC 6.3.
We use the Web Services extensively in-house and they are being used more and more inside BC and when the solutions team are doing custom developments. In particular we have used them for our integration with our BIM Module, BC Assure and the UNIT4 Agresso Document Archive.
If you are interested in finding out more about the Web Services, contact your account manager and they will be happy to discuss how they can benefit you.
You may wish to arrange some technical consultancy to get a hand from us in order to get you started with your developments, but ultimately the Web Services API is free to use, so what’s stopping you? Get started on building your Web Service API and get more out of BC in the way you want it!
For REST, I found the following resources useful:
For the OAuth Protocol, I found the following resources useful:
In the next article in this series, Keys in OAuth, I will describe what you need to have setup on your BC before you can start using the Web Services on that server. In the meantime, you can have a look at a fully expanded version of the code sample which I will explain in detail later in the series.
The examples produced here are written in PHP. I have developed this using PHP 5.3.3 and run the samples on a CentOS 6 server.
For these I used the PECL library oauth. To get this installed, it is necessary to install
pcre-devel. This is done by running the following shell commands:
yum install php-devel yum -y install pcre-devel
Once this is done, you can install the oauth library:
pecl install oauth
You might want to check you can create an OAuth object in a test PHP script to ensure the library is successfully installed. Once this is done, you can create the scripts.