For systems that are built on top of diverse tech stacks, including both static and dynamic types languages, what is in practice some ways to have the API contracts published and enforced?
Some wiki documentation would just stale over time so I was wondering what are various approaches used in industry for this?
- Why the downvote? Is this SE not relevant for the question? Can it be improved?Jim– Jim2020-11-02 11:19:32 +00:00Commented Nov 2, 2020 at 11:19
- It's a bit of an open-ended discussion question, rather than a question that has a specific answer.Simon B– Simon B2020-11-02 11:27:55 +00:00Commented Nov 2, 2020 at 11:27
- @SimonB: Any suggestion of how I could improve this?Jim– Jim2020-11-02 11:30:03 +00:00Commented Nov 2, 2020 at 11:30
- See Why do 'some examples' and 'list of things' questions get closed?. Moreover, askers on this site are expected to do some research on their own before they ask, show us what they found and why it did not suit their needs.Doc Brown– Doc Brown2020-11-02 11:44:21 +00:00Commented Nov 2, 2020 at 11:44
Add a comment |
1 Answer
Two main ways to do this:
- Write compatibility test suite that calls the API and verifies that the implementation conforms with the properties required by the API contract. Ideally, this should be an automated test so that the test is repeatable and consistent, but in some cases you can write a certification test that integrators need to run through before they are allowed to connect to production system.
- Write a schema file (e.g. XSD, JSON Schema) that implementations can run against their implementing. In many cases, clients can use schema files to automatically generate client SDK, and servers can use the schema files to generate implementation stubs. But schemas is useful even if you don't auto-generated from it; most schema languages have validators that you can run example documents against the schema to check if the document matches the schema.
- Could you please elaborate a bit on each item? Seem like very good ideas to meJim– Jim2020-11-02 11:31:42 +00:00Commented Nov 2, 2020 at 11:31
- E.g. for (1) who owns the wring the test suite? The server side or the clients? How do the test suite get updated as the API evolves? For (2) are there tools for automatic creation? Or is it manually done?Jim– Jim2020-11-02 11:38:02 +00:00Commented Nov 2, 2020 at 11:38
- 1) "who writes the test suite" In most cases this is going to be whoever side defines the API specification. The compatibility test suite is basically just going to be an executable form of the specification. API can also be a shared responsibility, in which case both sides might be involved in writing and maintaining the test suite. 2) there are tools to validate schemas, I had never seen tools to generate schemas, but IMO, it sounds like it'll just over complicate stuffs. Writing schema is not that complicated, and it forces you to think what you want to enforce.Lie Ryan– Lie Ryan2020-11-02 11:47:43 +00:00Commented Nov 2, 2020 at 11:47