API-first and REST, can they complement each other?

In a time where the quality demand on web services gets higher and higher, but time to market is equally important, API-first has established itself as the silver bullet. However, the API design process is a difficult one that requires a lot of thought and rigour. A backwards-incompatible API change can easily become very expensive when an API is critical enough.

In this talk we will focus on the API design process, its intricacies, the standards that you have to absolutely be familiar with and last, but not least, testing. Given Apache Sling’s URL parsing rules, we will show how control-plane APIs can co-exist with the delivery APIs and how we can make sure that we test both the API definition and the implementation.

After the talk, the attendees should have a better understanding of how a well designed API looks like, get a list of tried and tested Java libraries that can be used for validating APIs on top of Apache Sling and see how other companies in the field manage the APIs they make public.


Is it possible to generate code (for example, servlets) in AEM from OpenAPI?

Henry Kuijpers

Maybe https://github.com/shinesolutions/swagger-aem can be nice to check?

Stefan Seifert

that was 2019: https://adapt.to/2019/schedule/swagger-aem-an-openapi-specification-for-aem

Radu Cotescu

We use https://github.com/OpenAPITools/openapi-generator - there’s a Maven plugin and you can configure which specific generator you want to use.


This framework is really good. what process should be adopted to minimize rework when there is a need to change the contract mid development as multiple teams would be using this to develop parallelly.

(see answer in talk video)


Is it a good practice to overlay standard gql interface with with custom filters or servlet to customize input and output

Radu Cotescu

No. You should handle all the processing in your GraphQL layer, so that you make sure that you still obey the schema. In the Sling API you can have your own GQL fetchers or directives.


UI team has to use mock data in order to develop UI in parallel. Should this part (providing mock data) also be included into API development flow?

Radu Cotescu

We do that by always providing examples in the OpenAPI definitions for everything. In addition, we have also encouraged the UI developers to use code generators like we do on the backend, so that all changes are managed at compile time for both clients and providers.