DEV Community: marian-varga

JSON Schema default that complicates compatibility checks

marian-varga — Fri, 10 Apr 2026 07:19:54 +0000

Automating API contract checking can save you from human mistakes. The syntax part of API contracts is a low-hanging fruit that can be improved quickly by centralising the schemas on a schema registry.

Schema registries not only store the schemas, they can also perform automated compatibility checks on them.

Talking about API integrations, a bullet-proof, yet practical, definition of what is a non-breaking (compatible) change vs breaking (incompatible) is not trivial. It does not involve just the provider/owner of the API, but also all its consumers. For some consumers the change may be a breaking one, for others not.

JSON is very popular because it is simple and because JSON documents can be read by humans directly. But when it comes to automating schema compatibility checks, it shows some weaknesses.

Yes, you can tame the JSON data sent over your APIs to some degree using OpenAPI or AsyncAPI.

Let's take the Petstore example. If you pretty print the OpenAPI spec and scroll down to the section starting with

        "components": {
            "schemas": {

you can find JSON schemas like this one:

        "Category": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "example": 1
                },
                "name": {
                    "type": "string",
                    "example": "Dogs"
                }
            }
        }

Based on this you can tell that { "id": 1234 } is valid, but { "id": "1234" } (using a JSON string instead of the number) is invalid.

However, what the schema does not tell explicitly is, that a document with any extra fields is valid, too.

In this document

        { "id": 1234, "name": "my category", "newAwesomeField": true }

I added the "newAwesomeField" that is not specified by the schema, but any application that reads the JSON document should accept it. This usually works because deserializers like Jackson ignore unknown fields by default.

Actually, the above JSON Schema is equivalent to this one:

        "Category": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64",
                    "example": 1
                },
                "name": {
                    "type": "string",
                    "example": "Dogs"
                }
            },
            "additionalProperties": true
        }

The "additionalProperties" JSON Schema attribute is commonly omitted. Its default value is true, meaning that documents with any properties on top of those explicitly listed are valid.

Now what if someone decides to create a new version of the schema, making the "newAwesomeField" official? Let's say the field is defined as follows:

        "newAwesomeField": {
            "type": "string",
            "example": "Some awesome free text"
        }

Now the document { "id": 1234, "name": "my category", "newAwesomeField": true } that was valid with the old schema becomes invalid! It is because the new schema defines newAwesomeField as a string, whereas in the document we use it with a boolean value.

This default openness of JSON Schema creates a barrier for a safe evolution of schemas.

The other two commonly used schema languages (Avro and Protobuf) are stricter, making the schema evolution with them more controlled. It makes sense for them because they are designed for efficient binary serialization. Too much flexibility (including for example that you can shuffle JSON fields in any order) is not good for efficient processing.

If you are using JSON in your API payloads and want to make compatibility checks safer, it may be a good idea to include "additionalProperties": false in your JSON Schemas.

If I triggered your interest, you can read all the details on how the additionalProperties work.

Don't kill the bearer of bad news

marian-varga — Mon, 15 Dec 2025 18:15:39 +0000

Have you ever been in a situation where you had to manage expectations of people who thought a software project was on track and delivering the required features would be easy? Having to explain technical debt, gaps in feature specifications and risky external dependencies?

It is scary to tell the unpleasant truth. You don't want to sound negative, decrease the team morale and make managers angry. And there might be managers or customers who will dislike people telling them such not-so-nice news. On the other hand, staying silent about problems and risks won't make them disappear. It is more likely they will only grow and suddenly blow up when it is too late to adjust plans and mitigate them.

People telling bad news early and accurately are important. And so are parts of the system doing the same.

In microservices architectures and many other real-world systems that have to be distributed it is common that a service, in order to execute a request, calls APIs of another service or services.

Some architectures even contain dedicated services whose purpose is to translate the communication between two parts of the system, typically between a legacy application and new services or between in-house systems and external (hard-to-influence) services. Such services are often called a gateway, anti-corruption layer, adapter or facade.

It is not enough if these services can translate the data in positive scenarios. If something is not right, forwarding it as-is to the other side or even worse, ignoring it, can lead to issues that are hard to detect and fix.

Imagine a service A calling service B that in turn calls service C using a REST API. What should service B do if service C returns an HTTP 4xx status? Just forwarding the same error to A and/or writing it in a log using a generic exception handler won't do.

+-----------+        REST       +-----------+        REST       +-----------+
| Service A | --------------->  | Service B | --------------->  | Service C |
+-----------+        ??? <----  +-----------+     HTTP 4xx <--  +-----------+

Service B is supposed to translate between the worlds of C and A. It probably adds some more data and context when calling C, so C's response may make no sense to A and will be unusable to fix the problem.

4xx statuses in HTTP mean client error. But can we be sure it is A's fault if C returned a 4xx error? Service B should expect the most probable errors returned by C, detect them and translate them to responses that A understands.

For errors returned by C that B does not expect, it is not clear if they are caused by A or B, so to be on the safe side, it may be more correct to return a 500 (internal server error) to A because it is an error that B failed to identify.

Also, B should validate the data in the request from A. In case the data cannot be used to create a valid request for C, it should not even make the call to C and return a meaningful validation error to A. Skipping the validation may lead to strange hard-to-understand errors coming from C and forwarded to A or written to logs.

Correct error handling and logging at all levels of a software system is essential to prevent bad things from becoming even worse. Especially in distributed systems where it is very common that the original context is lost.

Why did we disable CSRF protection?

marian-varga — Mon, 01 Sep 2025 13:04:45 +0000

All your services / applications and the whole solution may be working from the functional perspective, however there are still many things to do before you can go to production. One such activity is making sure that there are no security vulnerabilities.

Suddenly, a colleague of yours is asking: Why do we have this

httpSecurity.csrf((csrf) -> csrf.disable());
here??? We need to be protected against everything, including CSRF, right?

(This is from Spring but you may see something similar with other frameworks.)

You start scratching your head trying to remember what CSRF actually is... Or you know immediately because you've read this post :)

Imagine two people, Alice and Eve, working with their computers, sitting next to each other. Eve is evil, trying to attack Alice, but to not show it, she will never look at Alice's keyboard or display. Instead, while Alice goes for a tea, Eve will plug her own keyboard in Alice's USB port.

When Alice comes back and unlocks her machine, Eve can type something evil that will be executed in Alice's name, like "send money to this account" or "drop the database". Of course, Eve has to guess the moment to type when Alice puts focus on the right window...

The attack works because Alice's machine can't tell that it is not Alice, but somebody else typing.

CSRF means Cross-Site Request Forgery; instead of keyboards connected to the same computer we have HTTP requests sent from the same browser.

One of the requests is a legitimate login to a web application, e.g. internet banking, resulting in a session cookie being stored by the browser. Another one is a request from a malicious website that looks exactly the same as a legitimate request to send money.

The session cookie is added to the request automatically by the browser, so the request is authenticated and will be executed by the server!

How to prevent CSRF? We have to make sure that the sensitive requests cannot be guessed (excluding the automated cookie appended by the browser). So we need something dynamic, random, added to the request explicitly.

The CSRF protection in Spring (or another framework) checks an additional non-cookie parameter in the HTTP request.

Luckily, well-designed REST APIs usually don't rely on session cookies, they are stateless. That includes authentication where the preferred method is Open ID Connect (OAuth). An authentication token (in the JWT format) is sent in the "Authorization" header with every request. You can learn more about securing REST APIs in our book (see love2integrate.com).

So, you can reassure your colleague that with stateless APIs that don't use cookie authentication it is OK to have the CSRF protection turned off.

Can an application suffer from jet lag?

marian-varga — Tue, 08 Jul 2025 04:23:40 +0000

When designing APIs and data models, I prefer simplicity and avoid ambiguity.

For date and time, programmers like using epoch time. This is the number of seconds or milliseconds since January 1, 1970. It requires just one integer field, making it easy to compare and manipulate.

My favourite geek joke is that the world should switch from measuring time in hours and months to using megaseconds and gigaseconds.

We accept UTC only?

APIs are often crafted by backend developers who aim for simplicity. Sending epoch times as integers might be harsh. However, even if using the more human-readable ISO string format (YYYY-MM-DDTHH....), requiring all time fields to be in UTC is just shifting responsibility onto others.

Relying on the client to handle time zone conversion can lead to issues, especially if the time is entered by users via a GUI.

Even if your backend only works in a single timezone, your users might be in different time zones.

People think in local time, not UTC. If the frontend provides UTC time, it drops the timezone information. Later, when displaying stored UTC time, the frontend must guess the timezone. An incorrect guess can confuse users.

A client device's timezone setting might be wrong, so your application shouldn't depend on it. You might want to show the assumed timezone on the GUI or let users change it if needed.

Defining the API time field as date and time with timezone (not limited to UTC) prevents information loss. The Java ZonedDateTime class models this well.

However, this adds complexity, especially in the persistence layer. Your database might not support datetime with timezone in one field. You may need two fields: one for UTC time for easy sorting and another for the timezone.

Date without time = easy?

Business needs often deal with dates that don’t include a time component. For example, a subscription may be active from day X until midnight of day Y.

But don’t remove the time information from your APIs without careful thought. Timezone differences can make day Y in Europe become day Y+1 in Australia. (I enjoy celebrating the Australian New Year so I can sleep at normal hours. I know, I’m old. And I have kids.)

So, ask the business what timezone the date ranges apply to. Double-check if you need the time component with the date inputs!

API killed the transaction star

marian-varga — Mon, 30 Jun 2025 14:24:34 +0000

Building applications from various services is common today. This can mean using a microservices architecture, which allows teams to develop and deploy features quickly. It may also involve integrating legacy systems with new ones or connecting external services to in-house systems.

However, distributed systems come with challenges. One major issue is that we can't depend on transactions like we did with centralized applications. Transactions provide consistency. They ensure that changes across multiple database tables either succeed together or fail together, keeping data consistent.

In distributed systems, achieving this level of consistency is difficult. Data may be stored across multiple databases linked by remote APIs. We can, however, aim for "eventual consistency." This means we accept temporary inconsistencies but expect them to resolve automatically.

If you need to combine a transactional resource (like a database) with one non-transactional resource (like a remote API), you might try these steps:

Start a transaction.
Apply changes to the database.
Call the remote API.
Commit the transaction if the API call is successful; otherwise, roll back.

This approach has drawbacks. Step 4 may fail, or the service might crash (e.g., due to Kubernetes) before reaching it. Additionally, the time spent calling the remote API adds to the transaction time. Long transactions lock objects for a long time, leading to performance issues or deadlocks.

If you have multiple non-transactional resources to call, this simple method won't work.

A more complex solution is using compensating transactions. Here, you commit transactions for the transactional resources right away (or don't use transactions at all). If a non-transactional operation fails, you must reverse the changes made so far.

Picture booking a summer holiday deal but needing manager approval. If your manager declines, you'll need to cancel your booking. This cancellation is your compensating transaction, but the holiday has to be cancellable.

If you're updating a large, complex resource, it can be tough to identify what parts you're changing and how to reverse those changes. If another update occurs simultaneously, conflicts can arise. For example, if you are raising a price from 10 to 15, but meanwhile another update sets it to 12, should you revert to 10 or 12?

The most resilient distributed systems tend to be event-based. Each state change in a service is an irreversible fact, communicated through an event message. Consumers of these events must respond accordingly to maintain consistency.

To ensure the data in the service database aligns with the events sent, we often use the Outbox pattern. First, you make changes to the service database within a transaction and then insert a record in an "outbox" table for the event. Transactions do remain useful in distributed architectures.

The outbox table is checked regularly, and messages are sent via messaging infrastructure (like Kafka). If a service restarts, the same event might be sent twice.

Thus, event consumers must be idempotent. If they receive a duplicate event, the outcome should be the same as if they received it just once.

What has been your experience with managing consistency in distributed systems?

Should we echo POST and PUT requests?

marian-varga — Tue, 24 Jun 2025 13:39:30 +0000

There is a common REST API design practice developers often apply without much thinking.

When implementing a POST or PUT endpoint, we usually return the created or updated entity in the HTTP response body.

I am not sure about the origin of this convention, but I suspect it can be related to the urge to reuse data models: We already have a model for the entity that is used in the request and in the GET response, so why not use it also for the POST and PUT responses? I once wrote a blog post where I show how reusing too much can lead to an incorrect API design.

There is nothing in the HTTP protocol or REST architecture telling us to echo back what we got in a POST or PUT request. On the contrary, there are some arguments against it:

waste of network bandwidth and increase of response time, especially for large entities
the client already has the data because it has just sent them in the request
it can lead to incorrect assumptions on the client side that the returned data are always up-to-date, but that might not be true if some other request on the same entity is performed in parallel

Someone pointed out that there can be some "additional processing" happening on the server and therefore it may be necessary to return the entity after that processing. For sure, if a new entity with a new ID is created in a POST request, we should return the URL of the new resource (or at least its ID).

But even if there is some more information generated on the server, why do we automatically assume that the client needs the modified parts or the whole entity data? It goes against the single responsibility and CQRS (Command-Query Responsibility Segregation) principle: a POST or PUT is expected to do a create/update. If the client needs to read the data, it can use a GET request.

Remember, APIs, like all interfaces, should be minimal. Only expose what needs to be exposed. Adding stuff to an API data model is easy (non-breaking), but removing it is hard.

What do you think? Do you return the entity as the response from your POST and PUT endpoints? Always? Sometimes?

OpenAPI examples are like comments

marian-varga — Mon, 16 Jun 2025 11:18:45 +0000

For projects involving a lot of integration I recommend to use the specification-first approach, starting with an OpenAPI document and generating implementation code stubs (e.g. in Java) from it because in my opinion it brings a better separation of the implementation from the specification and helps in the API maintenance. (See my blog post)

However, there are certainly things that can be improved in the OpenAPI specification itself and even more in the supporting tools. One such thing is the support for examples embedded in an OpenAPI specification. They are not mandatory, but including them will help both humans and automated test tools in understanding the data expected on the API.

Unfortunately, the OpenAPI specification says that the examples "should" match the schema, so it is not required for them to be valid. This means they are like comments in any language, whose syntax is not checked.

This is unfortunate because if someone changes a schema, it is easy for them to forget to make the respective changes in the examples. Outdated examples can be misleading. To prevent the situation, you can use a tool that validates the examples.

Hexagonal+optimistic may not be easy

marian-varga — Tue, 25 Mar 2025 17:10:51 +0000

Hexagonal or ports & adapters architecture is commonly used to structure the services so that details of the communication (including APIs and database access) do not leak into the business logic code.

One problem with hexagonal architecture is that you need to map your data a lot between objects used in your API and persistence (ports) and your business logic (domain). Of course, tools like MapStruct for Java help in this.

With the mappers in place, a pattern commonly emerges where at the beginning of an operation a persisted entity is read from a database, it is mapped to a domain object, some updates are made in the domain module and the updated domain object, after being mapped back to the persistence entity, is saved to the database.

This pattern has a problem that it does not handle concurrent updates out of the box. If the database record is changed by someone else between your database read and write, your write blindly overwrites the record with old data, leading to data loss and/or corruption.

Transactions might help, but you would need to remember to start the transaction and ask for an exclusive lock (SELECT FOR UPDATE in SQL) at the time you read the data. And you have to make sure the span of your transaction is until you save the modified data back.

But transactions and exclusive locks create an overhead that can slow down your system.

One option is to refactor your persistence code so that it provides methods that do atomic updates of exactly that part of your document that needs to be updated by the business operation. For that, you might need to stop using the repository pattern and go straight to e.g. MongoTemplate to have access to those atomic operations. And of course it has a big impact on the overall design of your application (service), you cannot do "read full object-map-modify-map-save full object" anymore.

On the other hand, if you do not expect many concurrent updates, you can avoid that refactoring by introducing optimistic locking. Optimistic locking is no locking actually, it means adding a version number field to your persisted data and when writing back, checking if the version matches.

Now the question is, how to preserve the version number when your database entity is mapped to the domain object and back? From my analysis and research it usually means that you need to relax the hexagonal architecture rules a little bit. For example, you can decide to put the version field in the business object even though it feels like it is specific to the persistence adapter.

Here are some interesting links
Hexagonal Architecture and database concurrency (StackExchange)
Building an Event Driven Architecture – Lessons Learned (see the comments below the article discussing the optimistic locking)

What is a URL?

marian-varga — Tue, 25 Feb 2025 12:02:30 +0000

We type it multiple times every day, we call it "a link" or "a web address", yet how many of us actually remember why it is called a URL? And why is it important for a good REST API?

URLs (Uniform Resource Locators) are a subset of URIs (Uniform Resource Identifiers). There is another subset of URIs, the URNs (Uniform Resource Names). All URIs identify resources that are the basic building stones of REST.

A URL (unlike a URN), besides being a unique identifier, contains information about how to locate and access the resource. The URL https://dastalvi.com/contact tells a client to

use the HTTP and TLS protocols (https),
connect to the server with the domain name dastalvi.com
and pass the path /contact to the server; the path is used to locate the resource within the server.

When creating something new, including an API, we often start by copying an example of something we know works. The Petstore sample API from Swagger is a famous example that we might want to use as a starting point, especially if we want to create an OpenAPI specification for our API.

However, not every part of even a well-known example is good to copy without thinking if it fits into our context. Let's take a closer look at the operation to update a pet using the PUT method. Can you see something dangerous?

Clearly, the specification reuses the same Pet schema containing all fields of a pet including "id" for PUT /pet, POST /pet and GET /pet/{petId}

Reuse is a good thing as it eliminates duplicates, right? But not all duplicates are good to be removed. Trying to be too clever and use the "id" from the PUT payload to identify the pet to be updated and removing it from the URL takes away an important feature of our URL: that it should be a URI, a unique identifier of the resource!

The PUT method should be idempotent and it should replace the whole resource (identified by the URI) by the content provided in the request. The resource it modifies is the one we can retrieve by GET /pet/{petId}, where we clearly see that the "id" is included in the URL (because the GET method does not have a request body).

Probably a more realistic approach is described in the API guidelines from Microsoft. It admits that there is usually a collection of entities (pets in our case) we work with.

The "Changing collections" section shows us that the PUT method should indicate which collection item we want to update.

On the other hand, if we want to create a new item of the collection and let the server generate the new "id", we should use the POST method. Because sending multiple such requests will create multiple IDs, so this is exactly the situation where we need the non-idempotent POST.

What can happen if you skip the DTOs

marian-varga — Mon, 29 Jul 2024 17:23:18 +0000

It is nice that a framework like SpringBoot can do so many things for you.

You just need a JPA entity class plus a simple repository interface and SpringData gives you all you need for typical CRUD database operations.

You write a simple REST controller class and you have a REST API running, right?

Hey, but you forgot to write a DTO! But why do you actually need it when your app could work without it?

There are certainly some general reasons:

layered structure (e.g. hexagonal architecture or ports and adapters): for maintainability it is a good idea to decouple the external communication code form the core (business logic)
security and performance: if you expose the database structure in your API as-is, you will soon get to a point where you expose more than needed; that can be misused by malicious actors or waste resources (CPU, memory and network bandwidth)
DTOs, unlike JPA entities, can be immutable (you can use Java records) and that is good for data-driven (functional) programming style, nice unit tests, safer concurrency etc.

But other strange things can happen, too. I will show you one weird example based on my experience.

This GitHub repo contains a simple application that works without the DTOs. There is a User entity, each User can have multiple Transactions. We even have a Service bean between the repository and the RestController, catching possible database access exceptions.

As we want to make a production-ready application, we do not want Hibernate to generate the DDL. Instead, we have a schema.sql that creates the tables (later we may switch to Flyway or Liquibase). For our simple example, we also have a data.sql so that our tables are not empty.

When we run the application and call the API endpoint at http://localhost:8080/users, we get the expected JSON containing the users and their transactions.

Now let's pay attention to the two lines of code in the Transaction class, marked //!!

@JsonIgnore //!!

The first smell is that in the Transaction class we had to add the @JsonIgnore annotation to the User reference. Without that annotation the JSON serialization crashes due to infinite recursion.

Now let's imagine that someone makes a mistake by adding another field (description) to the Transaction entity, but forgets to adjust the SQL statements (or runs the application against an environment where the schema change has not been applied).

private String description;//!!

Of course, now the API call fails. But look at the error handling! The catch clause inside the UserService does not work as expected. Instead we can see a strange stack trace in the log:
GlobalExceptionHandler : Unexpected error org.springframework.http.converter.HttpMessageNotWritableException: Could not write JSON:

I once saw this situation (clearly, with an application much larger than this example) and it took me quite a while to understand why the SQL exception escaped the service and why I was getting an HttpMessageNotWritableException. Can you see it?

What happens is, the UserService class (via the UserRepository) only queries the USERS database table. The Transaction entities are not part of the result because of the default Hibernate lazy loading. Only when the Jackson deserializer tries to create JSON from the User instance, it invokes its getTransactions method that makes Hibernate fetch the Transaction entities.

This is why we get a strange stacktrace combining JSON and SQL stuff. The exception is caught by the GlobalExceptionHandler that does not know what to do with it, this is why the log message is "Unexpected error".

I hope this little exercise will make you understand more deeply how dangerous it is to allow different layers of your application to mix. Seeing just the "sunny day" scenarios of your application while it is still small may lead some developers to continue doing the wrong thing until it is too late.

You do not have to write the boilerplate code mapping the fields between your DTO and the other layers of your application. MapStruct can do it for you.

AsyncAPI: a practical look

marian-varga — Fri, 03 May 2024 10:47:39 +0000

On the occasion of the release of the new major version of the AsyncAPI I wrote a rather theoretical post encouraging the use of AsyncAPI as a platform-independent standard.

But a standard is only useful if it can help you in real-life development scenarios. Just a simple Google search reveals that the older sibling, OpenAPI, has a much larger and more mature community. In the case of a machine-readable API specification language the tooling support is crucial. I will describe my experience with the tools so far.

AsyncAPI Studio

studio.asyncapi.com is a nice online visualisation tool to check if your AsyncAPI specification is valid. The page says it is "BETA", but it looked quite reliable when I tried it.

Code generators: the devil hidden in the schema details

In asynchronous APIs, unlike the REST (HTTP) APIs, we usually do not rely so much on common features of the protocol used. Instead of things like HTTP verbs, status codes and standard headers we concentrate on the payload of the messages. So it is nice that there are code generators that can produce a ready-to-run Spring Boot or Spring Cloud Stream application, but the most important part is the code that serializes/deserializes the payloads. Topic names and broker specifics are usually placed in separate configuration files anyway.

Different JSON schema languages

At first glance the schemas part of AsyncAPI looks the same as in OpenAPI. But the specifications are not exactly the same. AsyncAPI even in its latest version 3.0 only requires its users (including tools) to support a schema based on JSON schema draft 7 (from 2018) plus features specific to Async API, see the "Schema formats table" section of the specification. There are two more recent versions of the JSON schema, the latest is called 2020-12. And OpenAPI has its own set of extensions over the JSON schema.

No luck with polymorphism

I will illustrate the limitations of the generators on an example schema using polymorphic types with a discriminator field.

asyncapi: 2.6.0
info:
  title: Example of schema using polymorphism
  version: 2.6.0
channels:
  pet:
    subscribe:
      message:
        payload:
          type: object
          properties:
            pet:
              $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      type: object
      discriminator: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    ## applies to instances with `petType: "Cat"`
    ## because that is the schema name
    Cat:
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    ## applies to instances with `petType: "Dog"`
    ## because that is the schema name
    Dog:
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              minimum: 0
          required:
            - packSize
    ## applies to instances with `petType: "StickBug"`
    ## because that is the required value of the discriminator field,
    ## overriding the schema name
    StickInsect:
      description: A representation of an Australian walking stick
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            petType:
              const: StickBug
            color:
              type: string
          required:
            - color

The above is a valid AsyncAPI specification (you can check it in the AsyncAPI Studio), however none of the currently available AsyncAPI code generators can generate a usable (Java) code from it. By usable I mean a code that uses the discriminator field value to choose what Java class to instantiate and then deserializes the JSON object in the instance correctly.

The "most official" AsyncAPI generator linked from the AsyncAPI site will follow the references in the "allOf" structure to generate the subclasses of the Pet class. But it will ignore the "discriminator" logic and actually fail because it does know what to do with the "petType" attribute repeated in the derived types (e.g. StickInsect).

A less important thing I do not like about the "official" generator is that it is implemented in JavaScript (it uses the schema generator library Modelina written in TypeScript). For a Node.js backend this may be nice, but for Java (JVM) based backends it is not ideal to have to invoke npm as part of the build process. Especially knowing that the OpenAPI generator that is much more mature and probably used for the synchronous (REST) APIs of the same backend service, is implemented in Java and runs in Maven/Gradle nicely.

If you convert the above schema to the OpenAPI format and run the OpenAPI generator on it, you get the polymorphic code that you expect.

In the Tools dashboard of the OpenAPI site you can find two more generators: MultiAPI generator and ZenWave SDK, both written in Java. Unfortunately these are even less mature than the JavaScript one: They don't even detect there are types derived from the base Pet type for which classes should be generated.

Conclusion

I still think it is a good idea to start using AsycAPI for asynchronous APIs. But beware of possible problems if you want to use complex schemas. The safest is to use just simple schemas and wait for the tooling to catch up. You always have to verify your schemas with the actual generator you want to use. Even JSON schema draft 7 contains concepts similar to the discriminator approach above (if-then and oneOf), but neither of them made the generators give me what I needed.

Actually, the AsyncAPI 3.0 permits to use the OpenAPI schemas in AsyncAPI using what they call a "Multi Format Schema Object". Although the specification does not require, only recommends to support the OpenAPI schema, I would really love to see tools supporting it so that we can share the same schema format for AsyncAPI and OpenAPI.

Why I don't like "v1" in an API URL

marian-varga — Thu, 21 Mar 2024 08:50:02 +0000

I've recently read a quite useful article on API design best practices.

But I wasn't quite comfortable with one point in it, the one advocating putting a "v1" in the API URL paths to support versioning. After thinking about it a little I have decided to explain my reasons in more detail.

TL;DR YAGNI & KISS.

Similarly to code expressed in more lines of code, adding more abstraction layers prematurely should be considered a liability, not an asset. Once we decide on the convention to put the version number in the URL, in order to be consistent, we have to incur the cost of maintaining the convention for all our API endpoints.

Moreover, having the version number can support a false feeling that making incompatible API changes is actually cheap. It is not. You have to think about all the clients of your API and support (including regression testing etc.) multiple versions of your API until you are sure a certain version is not used by anyone.

Another important thing to consider is that in practice it is quite hard to draw the line when exactly an API becomes backwards incompatible, for example:

Although it is not nice or recommended, it can happen that there are clients not ignoring newly added response attributes.
Is changing caching policy, returning a response using Transfer-Encoding: chunked instead of Content-Length etc. a compatible API change?
You just fix a bug in your API, but there may be clients who work around the bug and actually rely on the buggy behaviour!

Only the clients of your API can tell for sure if a change is really compatible or not.

In many cases you decide that even though in theory your API change may not be backwards-compatible, you just expect the clients to adjust. A typical scenario is when you have control over the development of the client(s), like front-end developers connecting to a back-end developed within the same agile team. Incrementing a version number in the URL in such a case "just because it is what the book says" would be just an unnecessary additional work and a cause of fights.

A major API change quite often brings a change of semantics of your endpoints, so maybe just renaming them to their accurate business meaning is enough and you do not need "v1" and "v2".

If you really need to support multiple versions, you probably just need it for one or a few endpoints.

Now if your "v1" is at the root of the path, you

either have to change the path of all endpoints when you just needed to change a few of them
or you break the path hierarchy because some endpoints will be under "v1", while others under "v2"

If "v1" is at the end of the path then you cannot deal with it as with a common prefix in just one place, you have to maintain it in all the endpoints. Doubts and inconsistencies can pop up very quickly: Is it /customers/v1/{id} or /customers/{id}/v1 ?

So, I think it is better to skip "v1" and wait until you really need a "v2". And when it happens, you should consider, instead of putting the "v2" in the URL path, to use an HTTP request header (either a custom one or maybe as a suffix of "Content-type").