iGarment Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== iGarment API Specification ======

===== Introduction =====

This article describe how to use API to exchange data with iGarment System. Please note that iGarment API infra structure can only work with Unicode (UTF8) data, thus only support if your company is using iGarment version 5 or above.

The exchange data is either JSON or XJSON depending on the HTTP Content-Type header. It is either application/json or application/xjson. XJSON (eXtended JSON) is a serialization notation design by iGarment Ltd. XJSON and JSON is interchangable. For details, please refer to the [[xjson|XJSON specification]].

We use JSON Schema to specify our document, if you want to learn more about JSON Schema, you may like to visit the following sites:

  * [[https://json-schema.org/|JSON Schema Official Site]]

  * [[https://www.w3.org/2019/wot/json-schema|W3G JSON Schema in RDF]]

''Although the JSON Schema specification may use attribute $comment to specify a comment, but we find it may be too combersome to read. Instead we will use # to for a comment. Any text after the # are comment and we will preprocess the JSON Schema file by removing our comments before we submit to the validator.''

===== API URL =====

The API URL is https://api.igarment.net

Example, an API call to get a purchase order AX-10021

https://api.igarment.net/jdoc/purchase_order/AX-10021

**Authentication method**

To use iGarment API, you need to obtain a API KEY from your account manager and put the domain (database name) and the api-key in the Authorization Header of each HTTP request. Note that Authorization Header needs to be encoded in Base64.

Example, let said you want to send an api request for the domain 'demo'.

  keyinfo = base64.b64encode(b'demo.igx-xxxxxxxxxxxxxxxxxxxxxxxxxx')
  headers = {'Authorization': keyinfo.decode()}
  

(Example in Apifox)

  var cryptoJs = require("crypto-js");
  
  const igx_key = 'demo.igx-xxxxxxxxxxxxxxxxxxxxxxxxxx'
  const keyArray = cryptoJs.enc.Utf8.parse(igx_key);
  pm.environment.set("igx_key", cryptoJs.enc.Base64.stringify(keyArray));
  
===== Error =====

We follow standard HTTP response code to indicate if a request is accepted or rejected.

A successed API request will return a standard HTTP 200 response. We will not used other HTTP 2xx status code other than 200 and there will be no data in the response.

Should there is any error occured, we use standard 4xx and 500 HTTP Error Response. There may or may not be additional data in the body to further ellaborate the error.

401 Unauthorized. 

402 Payment required.

404 Not found.

405 Method not allowed.

406 Not acceptable, a JSON object will be return to specified the reason.

500 Oops, we have a bug.

===== API Specification by catagory =====

  * [[db_api|Database Query API]]

  * [[doc_api|Document API]]