I-502 Traceability API Bugs
This post is targeted to all you technical folks out there who ever tried to use the BioTrackTHC APIs in Washington State. As you've likely noticed this API is a poor implementation. Here are some details of what makes it so crappy.
Not a REST style
May moons ago (c2000) internet software engineers came up with a methodology called REST. It's an elegant, best-practices way to design computer-to-computer interfaces (APIs). It defines things like common verbs and a hierarchical structure. REST style is so popular it's used by 1000s of internet software vendors large and small. REST has been around and well documented for over a decade. BioTrackTHC apparently didn't get the memo.
In REST style, we'd have APIs that look like this, which search for plants, retrieve one plant, modify and plant and then delete it.
GET /plants GET /plants/1234123412341234 POST /plants DELETE /plants/1234123412341234
The above style is as common as dirt today on the internet. What BioTrackTHC chose to use a single endpoint, with an action parameter. The request body is JSON but here we're just showing relevant portions on the same line as the request line. In their API there are no direct requests to access the objects or to search.
# No Equivalent to GET requests
POST /serverjson.asp { "action": "plant_modify", ... }
POST /serverjson.asp { "action": "plant_destroy", ... }
This omission of GET requests in their API is a critical flaw. There is no way to query the status of an individual item. Why intentionally build a system that make it difficult to access the data in the same?
Additionally, to query the system is built on top of some _sync* routines. These routines simply pull data in bulk from the system. Or a transactional-time-stamp like value can be supplied to provide “the latest changes”. This model is a known anti-pattern.
Get the little things Wrong
In these APIs the data transfer is used with an encoding called JSON, it's very very common. Everyone on the internet calls it “application/json”. In fact, according to RFC 4627 (c2006) this is the canonical name. BioTrackTHC calls their “text/JSON”.
Furthermore, the responses from their system use an incorrect media type as well, calling it “text/plain”. Well, it sure isn't “text/plain”.
Using incorrect types here makes a minor, inconvenient speed bump for anyone using these APIs. All the tools programmers (like me) make assumptions that things will work in a well defined manner using defaults that are widely defined and in active use on the internet. As a result of the stupid way it's done here we have to implement small work-arounds to deal with a system that is behaving in a non-standard way.
In addition to this flaw we have the secenario where fields are sometimes named “barcodeid” and sometimes it's “barcode_id”. Consistency #FTW!
Also, the usage of 'license_number' field. Some times this is the nine digit license number issued by the Department of Licensing which is commonly called a UBI here. Other times the 'license_number' field represents the six digit number issued by the Liquor Control Board.
The nice thing about inconsistency here is that it's consistently applied.
Flawed Authentication Model
The authentication system for this API is a joke. In order to access the API for the system you use the EXACT SAME CREDENTALS that a human uses to sign-in to the website! Yes, you've read correctly. No oAuth, no authentication tokens. In order to use other software on this API you have to give your username and password to that other software. There are at least three major things wrong with this:
- If the password changes it must be re-entered into other applications
- External applications must have a way to store the password and recover it to plain-text to use in the API call.
- It does not uniquely identify the party making the API request.
WeedTraQR has built a better system, with a better API.