How do you organize API endpoint contracts

Question

Where trying to improve the "confidence" we have in our inter-service communication.

Background: "Contracts" has been a matter of sharing a piece of code that defines an interface to implement, but over the years, the shared code changed, and a lot of different implementations (soap, msmq, rest etc.) sprouted up, which could all be said to implement the same interface, but in no way plays well together, whithout mapping, which caused a forest of "mapping" microservices to be implemented, which again, appears in different version. Development and Operations are both suffering from this.

Intention: I would like to define contracts for the endpoints on the outside, using something like Swagger or API blueprint. With swagger i can compare the swagger.json "contract" with the swagger.json for the service claiming to implement it, and with API blueprint, theres "dredd". For MSMQ based transports, we'll need some other approach, but i think contracts for the structure inside the messages could/should be conformed to for the same reasons as the http-endpoints.

The details about how to verify is not the question - the question is: How would you organize these contracts? Should we have an internal repository of contracts that can never be changed, but only occur in new versions, and then have the verification-process be told which contracts are (supposedly) implemented? Said contract-repo should be read-accessible by our verification-process, and to our (and external) developers...

Any inputs regarding the problems described in the background is appreciated, maybe I'm looking the wrong way for a solution?

Answer 1

The simplest solution IMO would be to utilize Pull Requests and good automated test coverage. It is a paradigm shift for those who are not used it but the the benefits are undeniable.

Github has some good docs: https://help.github.com/articles/creating-a-pull-request/ as does BitBucket: https://www.atlassian.com/git/tutorials/making-a-pull-request/

PRs only work when the entire team is on board. When a new PR is submitted, all developers except those on the critical path should stop what they are doing and take a few minutes to review the PR and leave comments like: this code will break the current contract for the Xyz method, please revisit or looks good. Many developers will simply leave a +1 if they think the code should be merged. Once you get enough eyes and approvals on the code it can be merged into the development branch.

In addition I would definitely make sure the team maintains good automated tests.

If you don't use git, Github or BitBucket and are unable or unwilling to change...

You could approach this in a couple different ways:

1. An internal system: This would generate and serve up API/Endpoint documentation based on method signatures and comments. You could use an automated tool to generate the documentation in HTML format. The problem with this is that the developers can easily change the contracts (method signatures) and commit that code which breaks things. The benefit would be virtually zero maintenance and a readable/searchable interface for developers to discover existing endpoint contracts.

2. An external system: This sounds more like what you want. You could do this in several different ways. One way would be to use a documentation tool like Yard to generate the current baseline docs, then assign the task of modifying them whenever a contract needs to change. Doing it this way would allow you to setup a separate (external) web stack as a service. Another way would be to build a separate app that models the functionality you desire. It would have Klass and Method models. The disadvantage would be that someone would have to maintain it. The advantage would be that developers could not easily change the contracts, or at all if you restrict access to the code.

Based on your use cases above, I would tend to go with a separate app. You could have a maintenance interface for a Team Lead or Admin to change a contract and version of the API/Endpoint. You could also have a read-only interface for developers to lookup things.

Workflow:

• Bug arrives at developers desk.
• Developer finds the root of the problem in a particular method.
• Developer looks up the method on the external contract site and discovers that the return value needs to change which will break the contract.
• Developer brings the discovery to the Team Lead or change control board
• Team Lead assigns developer to also modify the code that will break due to the change, accordingly
• Developer writes code to fix the bug (and hopefully automated tests)
• At this point the developer should be running a full regression test suite to make sure none of the new code has broken anything unexpected.
• Developer commits the (tested) bug fix

Answer 2

I ended up doing this, using tests as internal dev-documentation for the contracts https://gist.github.com/JulianMay/899d7cc7a82f1ca7c893547d37732f86