Best practices for validating your APIs against company guidelines

It’s useful for API developers to obtain feedback on whether their API design and implementation adhere to company guidelines. Checklists could be helpful for tracking a small amount of products, however for a listing with countless line products, they are able to become unwieldy.

Studying the list by hand and assessing the items isn’t easy. This is where automating validation and feedback comes in handy.

I suggest while using following three validation methods to checking whether your APIs are compliant with company guidelines:

1. Static Validation - Use static validation for things that may be checked by introspecting the API spec, that is typically written being an OpenAPI/RAML/Blueprint doc. Static tests can look for valid document (ex. OpenAPI), header names, URL template, HTTP methods, supported schemes, response codes, error description schema, supported authentication, model schemas, naming conventions, time and date formats, and much more.
2. Dynamic Validation - Use dynamic validation for things that you could validate just with functional endpoints. It will help you look for for consistency between your API spec and also the actual request/responses, API response time, TLS 1.1 or over, rate limits, etc.
3. Manual Review - You would employ a handbook review for stuff that require subjective evaluation. Perform the sources precisely model the domain objects? Exist overlaps along with other sources that may be normalized? Are nouns, plurals, and verbs used properly while designing sources? May be the API area minimal? will the API cover all use cases? Answering these questions not just requires manual review, but additionally good domain understanding and API design awareness.

You can handle static and dynamic validation through automation, and you may handle the manual review having a well-defined process. Let’s check out each in greater detail.

STATIC VALIDATION AUTOMATION

Static validation automation is best throughout the design phase, when it’s vital that you provide feedback towards the API designer around the API spec. The aim is to possess a tool like JSONLint, in which the API developer can paste the API spec and obtain feedback on what’s sporadic using the guidelines (as well as ideas to correct common errors). A Graphical user interface-based tool like JSONLint is simple to use, but you must have first-class API support for validation so that your APIs could be built-into continuous integration pipelines

• Static validation of API is implemented like a service deployed on Azure.
• An API-first design, that takes a OpenAPI document as input and offers output (JSON) on the number of guidelines were checked and the number of passed/unsuccessful. For unsuccessful ones, the problem location is pinpointed.
• Simple, web-based UI (much like JSONLint) implemented using Angular.
• All tests implemented while using popular and effective JavaScipt-based Mocha framework.
• Express (NodeJS) application implements the API. Azure tables can be used for storage and Azure message queues for job-scheduling.
• The Input OpenAPI doc is kept in the database and also the job ID is placed in to the queue. Among the available workers (Webjobs) get the doc and runs the Mocha tests onto it. It makes sense pressed in to the database. When the answers are available, the API responds with results. Please be aware, the asynchronous form of API is originating next.
• Splunk can be used for logging and telemetry.
• The UI/API access remains safe and secure through Azure Active Directory, that is associated with Citrix.

DYNAMIC VALIDATION AUTOMATION

When the API implementation begins and you will find tests written for this, we are able to start running the dynamic validation tests. Unlike static validation, which fits only from the API spec, ideas need actual API endpoints and tests to workout the endpoints so we must introspect the input/output payloads. This validation approach isn't amenable to manual input/output. An effective way to get this done would be to integrate it using the functional testing from the API.

• The API gateway includes a policy which does an (async) publish from the API req/resp (also known as API Callobj towards the service).
• The service API is implemented as Azure function, which stores the API Callobj in cache and runs the validations tests. Outcomes of the validation (JSON) are kept in Cosmos DB. It offers the amount of tests run and the number of passed and unsuccessful. For that failures, the precise area of the Callobj that unsuccessful is pointed out.
• Validation exams are implemented using Mocha.
• A Study API is implemented using Azure, which could retrieve the validation results according to service name and the timeframe range.
• Make use of a summarization job to periodically obvious old results and just support the review of the passes/failures per service.
• Make use of the summary API to obtain the service level validation summary (daily/weekly/monthly).

Manual Review

With manual review, we have to define a procedure and workflow within the tracking tool. As with every other process, it ought to be simple. It ought to also scale when more APIs are introduced in to the fold. For instance, rather of getting a centralized approval committee, which could be a bottleneck in large organizations, it’s better to possess a distributed and federated approval process.