Keeping track of internal API changes is not always as easy. In the midst of development, when everyone is swamped, well documented, well intended change could still come as a surprise to API user.
To easily keep track of internal API changes, some kind of automated API response monitor will be helpful.
JSON Schema
JSON Schema defines the schema of JSON response. We use ajv to validate our schema.
To help get started, I recommend the tutorial on tuts+ where you can find a great introduction to key features of JSON Schema.
On top of what’s mentioned in the article, I have a few extra tips:
- Use a schema generator — JSON Schema is pretty verbose. If you have a large response to validate, it could be very tedious to hand write the schema.
Try json-schema-generator. It only supports up to draft 4 (as of May 6, 2018) of JSON Schema specification. Convert to the latest draft manually should be manageable (migration guide). - Install command line interface of ajv (ajv-cli) to run ajv via terminal.
- White list approach — to keep track of addition and removal of JSON keys, my schema is defined to whitelist a list of existing keys. Validation fails if there’s new key or removal of existing key.
The gist below illustrates this approach…
Run ajv -s schema.json -d response.json in terminal. Validation will fail. another key is an extra key not allowed by the schema.
On the other hand, remove line 5 and 6 from response.json. Validation succeeds.
Wait, sku in line 5 is removed and validation still passes. To explain this… let’s look at schema.json. The schema defines a bunch of fields. The validator will look for key specified in properties for exact match and perform RegEx matching base on the pattern in patternProperties. If the field does not match anything in properties and patternProperties, the setting of additionalProperties kick in. If additionalProperties is set to false, any uncaught key will cause validation error.
To make sure required fields are present, make the property required in JSON Schema context.
Check line 23 above. sku is now a required field. You can add keys to this array base on your need.
Automate the validation process
You can easily set up your CI service to run the validation process via command line or make the validation a service.
I end up picking a dedicated an external service — Assertible which saves me tons of time.
Just sign up for a free account there. Dump the API request URL and schema (as a assertion criteria). That’s it!
You can schedule the test to run hourly (higher frequency available if you sign up for paid account).
I am very happy with Assertible. It validates API response, and, at the same time, doubles as API status and performance monitor. This is a huge safety net!
