API:Introduction

From Aligni Wiki

Contents 1 What is the API? 2 Web APIs 3 Security 4 Demo Site Sandbox 5 Introduction 6 Reading the Documentation 6.1 Request XML 6.2 Alternate Methods

What is the API?

The Aligni API provides secure access to the data within your site without having to actually use the Aligni interface. API access means you can develop custom applications that take advantage of your Aligni database. For example, you may integrate inventory updates with an online store.

Web APIs

If you are accustomed to standard language APIs such as C, Java, etc., the concept of a web API may seem a little foreign to start. The concept is the same, but the calling and parameter passing are done over a network rather than over registers and stacks within an application.

The important thing to realize is that you can still abstract a web API into a more familiar API by writing a wrapper in whatever language you choose. Most languages now have libraries available to help with this, including HTTP and XML support libraries.

Security

Security is provided through the use of an API Token. This token is a string of printable characters that is randomly created by the Aligni server. Along with the site subdomain in the URL of the request, the token authenticates you and provides secure access to the database.

You can disable API access by deleting the API Token at any time from your Site Configuration page. You can also generate a new API token at any time. We recommend you do this at regular intervals for increased security.

Demo Site Sandbox

The API token for the demo site (demo.aligni.com) is shown below. You can use this token to access the data within the demo site and test your API access implementation.

  oid3vLgynoy_Yl1gZkrgkLEq3J

Introduction

The Aligni API is implemented as XML over HTTP. This means that a simple XML request is sent to the Aligni server over HTTP and an XML response is returned. The utility curl can be used to make simple queries. For example,

 curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
   http://demo.aligni.com/api/oid3vLgynoy_Yl1gZkrgkLEq3J/part/728

Note that you must include two pieces of information with the header. The first (the Accept) indicates that you expect XML in return. The second (the Content-Type) indicates that you are sending XML, although in this example no request content is actually sent.

The above request returns the data on the part in the demo database with id=728:

<?xml version="1.0" encoding="UTF-8"?>
<part>
  <id>728</id>
  <partnumber>000019</partnumber>
  <manufacturer_pn>C0603C104K4RACTU</manufacturer_pn>
  <manufacturer_id>147</manufacturer_id>
  <parttype_id>47</parttype_id>
  <comment>SM-0603, 10%, 16v, X7R</comment>
  <description>Ceramic capacitor</description>
  <value>1.0e-07</value>
  <value_text>0.1 u</value_text>
  <allow_fractional>false</allow_fractional>
  <rohs>1</rohs>
  <committed>true</committed>
  <active>true</active>
  <created_on>Wed Jan 25 04:11:47 UTC 2006</created_on>
  <stock_price>0.009</stock_price>
  <pcb_footprint>CC1608-0603</pcb_footprint>
  <schematic_symbol>Capacitor</schematic_symbol>
  <three_d_model>CC1608-0603-Z04.sldprt</three_d_model>
  <quotes>
    <quote>
      <id>128</id>
      <vendor_id>40</vendor_id>
      <price>0.009</price>
      <quantity_min>4000</quantity_min>
      <quantity_mult>4000</quantity_mult>
      <leadtime>0</leadtime>
      <updated_on>Thu Nov 30 04:30:46 UTC 2006</updated_on>
      <expires_on></expires_on>
    </quote>
    ...
  </quotes>
  <vendor_part_numbers>
     ...
  </vendor_part_numbers>
  <alternate_parts>
     ...
  </alternate_parts>
  <inventory>
     ...
  </inventory>
  <partlist_parts>
     ...
  </partlist_parts>
</part>

Reading the Documentation

For each API "method," we provide the command, description, request (if applicable) and response (if applicable). The command is provided as an HTTP request and has a method and URL.

The HTTP methods are either GET, DELETE, PUT, or POST. The URL is abbreviated and assumes a standard prefix for your site and API token. For example,

 GET /contact

would imply that you should send an HTTP GET request to the following URL:

 http://mysite.aligni.com/api/my_api_token/contact

Because the site URL and API token are the same for all API accesses to your site, we have simply left them off for clarity.

Request XML

Many of the API methods do not require a request other than the HTTP method and URL. Methods that require you to provide data as input, however, will require an XML request. For example, to create a new contact, you will need to provide the contact details in XML as part of the request. Here is a command which will create a contact on the demo site:

 curl -H 'Accept: application/xml' -H 'Content-Type: appliation/xml' \
   -d '<contact><first_name>John</first_name><last_name>Doe</last_name></contact>' \
   http://demo.aligni.com/api/oid3vLgynoy_Yl1gZkrgkLEq3J/contact

If both a request and response are typical for a particular API method, the request XML will be shown first followed by the typical response XML.

Alternate Methods

Deleting database entries requires the use of the DELETE HTTP method:

 curl -H 'Accept: application/xml' -H 'Content-Type: appliation/xml' \
   -XDELETE \
   http://demo.aligni.com/api/oid3vLgynoy_Yl1gZkrgkLEq3J/contact/5

Your HTTP implementation in your client language will need to have support for the HTTP GET, POST, PUT, and DELETE methods.