BC Web Services

Posted by Shane Donnelly, Product Innovation Delivery Manager on 2 May 2019

Main Image

BC Web Services

BC Web Services: Introduction to the basics

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:
PHP snippet
 

If you were following the comments, you’ll know this code does the following:

  1. Authenticates with BC using OAuth
  2. Requests the contents of a folder
  3. Adds a new document to the folder

Two of the core concepts of Web Services are at the heart of this example: authentication and communication.

REST

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:

  1. Uses standard HTTP methods (GETPUTPOST or DELETE)
  2. Calls these methods on resources using URIs (fancy term for a web address)
  3. Uses standard Internet media type for the communication (XML, JSON, etc)
  4. Uses hypertext links for related resource
  5. Is stateless

Looking at this in relation to our example:

  1. The OAuth methods getRequestTokengetAccessToken and fetch all make HTTP requests. Getting the folder listing is done as a GET request. Adding a document is done using a POST request.
  2. The value of the $folderContentEndPointUri string that I used was the following URI://spd62bugfix.bc.local/api/artifacts/folder-958/contents.
  3. The parameters passed to add the document (namecontent_typecontent and kind) were passed as a JSON object.
  4. Discovering the URI for the folder contents is done by starting at the server root /api/ and finding the appropriate related resource via hypertext links. This is not explicitly shown in the example above.
  5. Each of the client requests contains complete authentication information as the server does not store session state. This information is sent as part of the HTTP headers in the OAuth methods.

As a result of this, the BC Web Services API can be referred to as RESTful, that is, they implement a RESTful communication protocol.

OAuth

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.

What version of OAuth?

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.

 

Notes on our usage

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!

Further reading

For REST, I found the following resources useful:

For the OAuth Protocol, I found the following resources useful:

So how do I use it?

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.

Download the .php code sample file here

A note on the PHP sample code

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 php-develandpcre-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.

Further guidance:

  1. Integration and Automation using BC Web Services
  2. Introduction to the basics
  3. The key to getting started