API First: Integration Approach

During the talk we will explore a growing need of distributed systems in API integration standards. We will compare API first integration approach with other options. Besides, we will talk about Open API specification and review relevant tooling.

[MJCtalks]

Hi everyone! Thank you for joining and we hope you enjoyed the talk. We'd like to respond to some questions and comments, that we couldn't cover during the live stream:

1. How does the "API First" approach impact the speed of development and deployment in a project?
Kiryl: - API First itself decreases late-stage integration issues so it decreases delivery time. Besides, using auto-generation tools such as one presented on the talk speeds up the development for sure. As a proof – see point 5 here 😉

2. Can you provide some examples of challenges one might face when implementing the "API First" approach and how to overcome them?
Kiryl:
- Main challenge IMO is that you need to manage API specs in some centralized way to avoid arbitrary changes to it on the one hand, on the other hand you need to keep you actual endpoints up to date with the spec. This challenge could be resolved by automation of Backend/Client generation and use as it was shown during the talk. Plus, you might consider contract auto Tests which verify the spec against your actual APIs.
- You might need some linter tool to ensure spec is always correct and confirms to OpenAPI standard and your project standards. Example of such tool is: zalando/zally: A minimalistic, simple-to-use API linter (github.com)

3. What are some common anti-patterns or pitfalls to avoid when using OpenAPI and an API-first design?
Kiryl:
- not keeping a specification aligned with actual endpoints, that can be covered by contract tests
- not aligning on data types conversion between OpenAPI and backend language
- overthinking of consumers’ needs – as API First implies the contract to be created first we might tend to add here just everything “for future need”. You will have to implement all corresponding code even though it might be not needed by API consumers

4. How does the "API First" approach affect the testing process? Are there any specific testing strategies you would recommend?
Kiryl:
- if you have API auto-tests (likely yes) early contracts allow testing team to start preparing their scenarios, scripts beforehand, not waiting for actual API implementations. Besides API mocks can be easily generated based on the schema.
- you may consider contract auto-tests which will verify that actual endpoints correspond to request/response schemas defined in the spec.

5. We use the OpenAPI generator in out Kotlin projects and I can guarantee: it significantly increases the speed of development and helps to automatically validate your API against schema. I can't imagine how to work without this approach!
Kiryl: Agree, same feeling! And thanks for participation!

6. How can I implement Api First approach except Open API instrument?
Kiryl: OpenAPI is a format of describing your API. For RESTful APIs, OpenAPI is the most used specification type nowadays, I can’t even recommend smth else here. However, if you deal with other communication types (technologies) such as async interaction via events or gRPS – you may use other spec types such as CloudEvents or gRPC specific format.

7. Can I we use OpenAPI generator plugin for other languages so we can integrate microservices written using different languages/platforms?

Kiryl: The plugin provides a bunch of generators for both server and client sides for different languages and frameworks, full list here:
Generators List | OpenAPI Generator (openapi-generator.tech)

8. What if my API providers/consumers not in Spring/java? Does generator support other frameworks/languages?
Kiryl: The plugin provides a bunch of generators for both server and client sides for different languages and frameworks, full list here:
Generators List | OpenAPI Generator (openapi-generator.tech)

Kiryl: thank you so much!

10. When do I push new version of api, i could still use old version and it won't be deleted in future?
Kiryl: short answer is yes. This is totally a matter of the retention policy in your antifactory (artifact repo), let me give you an example: we publish our API clients (Jars) into JFrog under a specific version. All versions are kept there so you can use any of those unless you have some policy deleting older versions.

11. What we need to do if will need to update the api schema? We can have situation when we need to update api schema but some of the services already use old version of the service which generated from old schema. How can we support such case?
Kiryl: You can publish a new API client version into artifactory upon each schema change, preserving old versions as well, so any API consumer can you whatever version it needs. However, if you do breaking changes to your API (not extending it but changing current APIs) – older clients will fail of course, here you need to introduce a new API version to keep old clients up until they are ready to switch.

12. How can we ensure security when adopting an "API First" approach?
Kiryl: it depends on which kind of security you’re talking about.
- If you mean API security – OpenAPI standard allows you to declare security related headers, or you might declare your own. But overall, API security is not a concern of API First, it’s more about the security design in your app, the schema just allows reflecting whatever security tokens/headers you use in API.
- If you mean security in terms of how secure you autogenerated code is – feel free to apply any vulnerabilities scanner to it.

13. Does this approach make any sense without contract testing? The API provider publishes a client that matches the API schema, but API consumers may use older versions. Without contract testing, it seems unreliable.
Kiryl: Contract testing is a vital thing, but I would like to mention the following:
You can publish a new API client version into artifactory upon each schema change, preserving old versions as well, so any API consumer can you whatever version it needs. However, if you do breaking changes to your API (not extending it but changing current APIs) – older clients will fail of course, here you need to introduce a new API version to keep old clients up until they are ready to switch. So the contract tests would at least allow you to make sure no one did breaking changes not intentionally.

14. Do we have alternatives for OpenAPI?
Kiryl: In terms of REST API definition – nothing same widely used nowadays afaik. However for other technologies/communication types – of course, e.g.
GraphQL schema, CloudEvent specification for event communication CloudEvents | or gRPC own format for remote procedure calls.

15. What do you think about using GraphQL for API-First?
Kiryl: absolutely fine, we used it on one of the projects. GraphQL has it’s own schema definition, the plugin provides GraphQL generators and schema validation capabilities, see here Generators List | OpenAPI Generator (openapi-generator.tech)

[CrownlessX]

It was quite interesting to see such an approach, but I would prefer gRPC over it - also provides a good contract, but also more readable and has better performance.
But in cases where only REST - it could work really well.