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.
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.
Authentication and Security
Account-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.
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.
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 60 per minute or 1000 per hour.
XML over HTTP
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/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,
would imply that you should send an HTTP GET request to the following URL:
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.
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/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.
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/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.