19.10. mSupply legacy REST APIs

This document describes an application programming interface for communicating with mSupply.

• Communication is over HTTP protocol
• All data is submitted and returned as JSON
• HTTPS supported- you should use it. If you want to restrict to only HTTPS, then block the HTTP port mSupply is using on your router.

• All requests must have standard HTTP basic authentication headers
• You must use SSL to secure your communications unless you want to tell the world your password.

• The basic syntax

• http://server_ip_address/type/resource/id_of_resource
  e.g. http://example.com/mobile/name/524
  will retrieve the complete record for name whose ID=524

• or

  http://server_ip_address/resource?field=blah,field2=blah2&sortby=+foo,-bar 
  e.g. http://example.com/mobile/name?name=foo@,customer=true&sortby=+name
  will retrieve all names whose name starts with "foo" and who are customers, sorted by name in ascending order (a to z)
  
  Note that a "/" is also allowed before the "?" in the URL e.g. http://example.com/mobile/name/?name=foo@,customer=true&sortby=+name

• Method: GET
• Note that all price data will be returned rounded to 2 decimal places.

• If you want a range of items, pass an HTTP header named “range” with a “from” and “to” value separated with a hyphen. See the following example to find out the right format for the “range” header.
  • e.g. to return the first 15 items:

    range  bytes=1-15

  • The server will reply with a header containing the item range and the total number of items found:

     items 1-15/568

• For string searches you can use “@” as a wildcard, as in the example above
  • ?name=@foo@ will return all names containing “foo”
  • ?name=foo@bah will return all names starting with “foo” and ending with “bah”
• Allowed query operators are:
  • =
  • # (not equal to)
  • >=
  • <=
  • <
  • >
• A query operator must be followed by a query value
• All resources returned are first filtered by the server to only return valid results for the store the user is logged in to.
  • Transactions: only transactions created in that store
  • Items: only items visible in that store
  • Customers (names): only names visible in that store
  • More on stores here
  • There is a full list of field names here but note that as of Wednesday 31 October 2012 they haven't been updated for mSupply v3.2

Use this resource to return lists of different types of categories in mSupply.

http://example.com/mobile/category?type=item

* You can filter on the category that items belong to by querying the category number and level. There are 3 categories (1-3) but please note that category 1 is hierarchical; it has 3 levels - level 1 is the parent, level 2 categories are children of level 1s and level 3 categories are children of level 2s. So, altogether you can query category1level1id, category1level2id, category1level3id, category2id and category3id. Note that all queries by category will return items that belong to that category and those which belong to all its child categories e.g. this query will return all items assigned to the level 2 category 1 which has an id of 4 and all items belonging to category 1 level 3 categories that are children of it:

http://example.com/catalogue/catalogueItem?category1level2id=4

This API is used by the mSupply stock web app.

• Must include authentication header
• Data in HTTP body as JSON
• Two types of POST/PUT: New and Update
• For New records:
  • Must use POST method without 'If-Match: *' header.
  • Append the id of the record to be created to the resource: e.g. POST http://example.com/mobile/transaction/134
• For Updates to an existing record:
  • Must use either POST method with 'If-Match: *' header or PUT method (headers ignored). e.g. PUT http://example.com/mobile/transaction/134

• Resource name: transaction
• Create a transaction
  • Submit a JSON object containing:
    • new_transaction_id (you must have already requested this from the server - see above )
    • comment
    • name_id
    • lines (contains a JSON array:)
      • item_id
      • quantity
      • directions (new in v3.84)
  • Payload.

    {"id": 34592,"comment":"test 1","name_id":3,
       "lines":[
           {"item_id": 19697,"quantity":10,"directions":"1t tid uf"},
           {"item_id": 22845,"quantity":5,"directions":"Take 5 tablets at 9 a.m. tomorrow"}
           ]
         }

  • successful completion returns a JSON object with “invoice_num” and a number
  • Assumed data: The following data is assumed and can not be submitted (will be ignored if you try)
    • The transaction type: it's a customer invoice (“ci”)
    • The store ID: it's the store you're logged in to.
    • The user: it’s the user who is logged in.
    • The entry_date: it's today.
    • The confirm_date: it's today.
    • The status: will always be “cn” (confirmed).
• Updating a transaction:
  • for supplier invoice we are editing only hold status for now. So json payload would be:

{"id":1002,"hold": "true"}
     

• for customer invoice we can also update line quantity

{"id": 34592,"comment":"test 2",
   "lines":[
       {"transline_id": 19697,"quantity":20},
       {"transline_id": 22845,"quantity":10}
       ]
     }

• Delete transaction lines:

  • {"id": 34592,"comment":"test 2","lines":[<all_lines>]

• Deleting a stocktake
  • e.g. http://127.0.0.1:8081/stocktake/123
  • Method: DELETE
  • Returns a JSON object containing a Description field with the value “stock take id xxx is deleted.” where xxx is the id of the stocktake deleted.

• <add here>

• <add here>

• Errors are returned as a JSON object with one item “error” whose text content is the error message
• e.g.

  {"error":"we can't take you seriously while you insist on wearing that cardy"}

• Here is a list of error messages you might see. Most are self-explanatory:
  • “No search parameter specified”
  • “No query parameter specified”
  • “Invalid resource specified”
  • “Invalid sort field specified”
  • “Invalid range header specified”
  • “No transaction with that ID found”
  • “Invalid transaction ID specified” (Different to above, in that you specified a non-numeric or negative ID)
  • “Yikes! Multiple transactions with same ID found” (you'll never see this error, or we'll be eating hats).