Alemba API

The Alemba API was introduced in 9.7 at the alpha stage of development, and, as such, is subject to significant change and review. It currently has limited functionality but is available for users to investigate. We would welcome your feedback.

As the Alemba API is subject to substantial updates, we would not recommend that you write anything to it that relies on no change.

The Alemba API is a RESTful API that is being introduced as part of a new generation of product software that will offer greater functionality and an improved user experience.

A RESTful API is an Application Programming Interface that follows REST (or Representational State Transfer) principles to allow one system to manipulate data on another. REST is a widely used protocol that provides a wide range of benefits over older protocols, such as performance, scalability and simplicity.

What is new?

The original vFire API is WCF-based (Windows Communication Foundation), which is procedural – it exposes a limited set of operations that manipulate a limited set of entities, and you need to know the name of the operation that you want to perform in order to use it. By contrast, the RESTful API is entity centric – it exposes all the entities within vFire, and the verbs that can be used to manipulate those entities follow the same standard pattern.

The RESTful API is also self-documenting, in that you can discover more detail about how to use the API from the API itself. The result is a more flexible and more intuitive way of working with vFire data.

How do I get it?

The Alemba API comes as part of the standard 9.7 install. It does not require additional installation, licensing or cost to use.

Installing the Alemba API will not impact your current API in any way. It is simply making it available for you to explore.

What is included in the Installation?

With the installation, you get:

  • 3 web services in 2 web sites in 2 app pools:
    • Alemba.Web
      • Authorization service – allows you to login and provides a token to use for all subsequent API calls
      • The API Explorer (see below)
    • Alemba.API – the main API
  • API Explorer – an interactive UI for understanding the API, including live search facilities as well as detailed technical information regarding all the available entities and actions
  • A wiki that will take you through the steps involved in setting up and using your Alemba API. (This will be documented in vFire Online Help when the API has been fully developed.)
 

Do I need to use the new API to run 9.7?

You do not need to use the Alemba API to use 9.7. However, it is a prerequisite if your users want to use the new vFire app.

Getting Started

The web services should be automatically configured as part of the install. However you are advised to check the settings in IIS, to confirm that the App Pool is configured for automatic recycling.

The base url is http://<servername>/<VirtualDirectory>/alemba.web.

To log in to the API explorer, key the following into your browser: http://<servername>/<VirtualDirectory>/alemba.web/alemba/api-explorer.

You will be prompted to log in. Do so using your normal vFire login.

The API Explorer gives you an overview of the entities covered by the API, their properties, and what actions are supported per entity. It also provides a visual interface for viewing live data. Full instruction is given in the API Explorer Guide in the wiki. Access the wiki by selecting the Help link on screen.

Once you are familiar with the API, you can start using the API programmatically. The Programmers’ Guide in the wiki will provide technical details.

Finally, using the API to achieve business level tasks, such as raising a Service Order, is covered in the Cook Book section of the wiki.

Comment and Feedback

As this is an Alpha release, and under active development, we welcome your feedback. Please contact the Service Desk with comments, queries and any observations that you want to bring to our attention.