API

The Aligni API provides secure access to 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. One common use of the Aligni API is to create a custom migration of part data from an existing part database.

Complete API documentation is available online here:

API Newsletter

To receive important updates and announcements regarding the API, sign up for our API Newsletter. This is the most effective way to stay informed about the Aligni API and keep your integration working smoothly.


Introduction

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.

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

Authentication and Security

APIAccessToken@2xAccount-specific authentication 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.

The site administrator grants API access by creating an API Token for each account that will have API access. Likewise, the site administrator may revoke access at any time by deleting the API Token. API Token management is available through the Account Settings page for each account.

API Token Expiration

The site administrator may optionally set an expiration time in the Site Settings to automatically expire API Tokens after a specified number of days. When this happens, a new API Token is automatically generated and an email is sent to each account holder reminding them to login to Aligni to retrieve their new API Token.

XML

Version 2 of the Aligni API uses XML for requests and responses. A full review of XML requirements is beyond the scope of this document but may be found online in multiple venues. You can use the W3C Markup Validation Service to validate content of your markup. Note that XML requires certain characters to be escaped in XML body content for both requests and responses, but this should be handled by most XML support packages in the language you choose for your client. These characters are:

Character Escaped Representation
" "
' '
< &lt;
> &gt;
& &amp;

HTTPS and SSL

HTTPS (HTTP over SSL) is required for all interaction with Aligni servers. This requirement includes API access. If you attempt to perform an API request via HTTP, you will receive a response redirecting you to the HTTPS protocol. Additionally, note that Aligni requires TLS version 1.2. If your network library attempts to connect using any other version, the request will fail.

Deprecation Policy

The current version of the Aligni API is v2. When the next version (v3) is released to production level, the current version will remain supported for one year and may become unavailable at any time after this period.

Breaking Change Policy

Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will proceed after 60 day notice through our API Newsletter. It may be necessary to deploy breaking changes without notice due to legal, performance, or security reasons. We apologize in advance for such rare situations.

Usage Guidelines

Aligni reserves the right to throttle or disable any site or account if requests exceed “normal” usage. The following are some loose guidelines suggesting what we consider “normal” for automated usage.

  • Record Indexes – Limit any index requests to once per day for automation. This includes requests for multiple full records (GET requests). Manual requests may be made more often if data is known to have changed.
  • Individual Records – Otherwise, API requests for individual records should not exceed 30 per minute or 1000 per hour.

Rate Limits

Current rate limits are established and enforced as follows:

  • Up to 30 calls may be made within a 60-second epoch.
  • If 31 or more calls are received within a 60-second epoch, the rate limit will be triggered.
  • For 5 minutes following a rate limit trigger, all subsequent calls will receive a “429 Too Many Requests” message.
  • After 5 minutes following a rate limit trigger, calls may resume.

Result Limits

Result limits are used to encourage efficient API practices. These are restrictions on the use of index endpoints to limit the total number of records over a particular period of time. Although we do not have result limits in place at this time, we may implement some restrictions at some time in the future to encourage efficient API practices. Per the Terms of Use, we reserve the right to limit user API access if usage exceeds the norm.

Best Practices

Please observe the following web API best practices:

  • Whenever possible, please queue API calls at the client in order to properly throttle execution to avoid hitting rate limits.
  • Cache non-volatile data on your end whenever it is feasible. Proper caching can dramatically reduce API calls required, improve efficiency, and avoid rate limits.
  • Avoid making API calls directly from a mobile app. Instead, send the request to your servers and make the API calls from the centralized server. This ensures that in the event of an API endpoint being modified, you will be able to make and deploy the change to your server rather than updating your app and forcing your users to the latest version.

API Implementation

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' \
   https://demo.aligni.com/api/v2/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:

https://mysite.aligni.com/api/v2/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>' \
https://demo.aligni.com/api/v2/oid3vLgynoy_Yl1gZkrgkLEq3J/contact</pre>

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 https://demo.aligni.com/api/v2/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.

Pagination

All API index or “list” endpoints support page-based (as opposed to cursor-based) pagination. You can select which set of results to retrieve by passing at least one of the following parameters: page and per_page.

  • per_page (integer) – determines the number of page results returned per API call. The default is 25 records.
  • page (integer) – indicates the page number for results a client requests.

For example, with page=3 and per_page=20 the user shall expect to receive records 41 through 60. In the event per_page parameter is not specified, the default page limit will be used.

Index endpoint page limits vary by object and will be documented on the respective endpoint.

Example curl

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
https://demo.aligni.com/api/v2/oid3vLgynoy_Yl1gZkrgkLEq3J/attachments?page=1&per_page=3

Response Header

The following values are provided in the response’s X-Pagination header:

{
  "total_entries": 10,
  "total_pages": 4, 
  "per_page": 3, 
  "current_page": 1, 
  "first_page": true, 
  "last_page": false, 
  "previous_page": null,
  "next_page": 2,
  "out_of_range": false
}