API Versioning with Document DB

Context

You have a document database, let's say DynamoDB. It has about 10m of person's name data, for example:

 The data is accessible through a highly scalable API and being consumed by 100+ other services. Over the course of few years there are some significant changes that require several iterations of the data and API, but all versions have to be maintained due to various legacy clients. The iterations are summarised as follow:

V2: Suffixes are now mandatory

V3: Title is now forbidden

V4: Givenname to change to Firstname

V5: Tony Stark Jr is now the supreme leader of earth, all Stark lastname must be capitalised

Forces

  • You only have one Document DB
  • All versions must be maintained

Solution

V2: Suffixes are now mandatory

Adding a new field is quite straight forward, we simply add to the Document DB
V1: leave it unchanged or update it to make sure that it does not return Suffix


V3: Title is now forbidden

Removing a field is trickier, since we have to maintain backward compatibility, we will need to handle it via API
V1: leave it unchanged or update it to make sure that it does not return Suffix
V2: leave it unchanged
V3: return the document without Title (unfortunately this will confuse future developers)



V4: Givenname to change to Firstname

Updating a field is even more complex, but despite maintaining backward compatibility, it is better to maintain the currency of the DB. Maintaining the currency of the DB is important because when we don't know when we can decomission the old versions, it is better to update the DB now, than later when the version is decommisioned

V1: change so that it returns Givenname and does not return Suffix
V2: change so that it returns Givenname
V3: change so that it returns Givenname and does not return Title (unfortunately this will confuse future developers)


V5: Tony Stark Jr is now the supreme leader of earth, all Stark lastname must be capitalised

Updating value is probably rare and done on case by case basis but whenever logical, it is generally advisable to maintain the currency of the database. In this scenario, this is best achieved with a versioned new field

V1: change so that it returns Givenname and does not return Suffix
V2: change so that it returns Givenname
V3: change so that it returns Givenname and does not return Title (unfortunately this will confuse future developers)
V4: no change or update it to make sure it does not return LastnameV5
V5: return LastnameV5 in place of Lastname





Comments

Post a Comment

Popular posts from this blog

Spring Boot 2: Parallelism with Spring WebFlux

Image
Spring Boot 2: Parallelism with Spring WebFlux Parallelism is rather unusual in Spring application, however when we encounter the need of HITLOL (HIgh Throughput LOw Latency), we need ways to make async calls. With Spring Boot 1, in high level definition, we can declare async on all the functions that are meant to be parallel and return Futures from there. Here is more detailed info:  https://medium.com/sipios/how-to-make-parallel-calls-in-java-springboot-application-and-how-to-test-them-dcc27318a0cf For Spring Boot 2, we shall employ Spring WebFlux libraries to accomplish parallelism. Mainly focused on functions: Mono.zipDelayError(), Mono.subscribeOn() and Mono.onErrorResume() The main function that drives the parallelism is zipDelayError(), the purpose of zipDelayError() as supposed to using zip() is to enable the other Monos to run to completion even if one Mono failed. AllDtos allDtos = Mono. zipDelayError (Arrays. asList (firstDto , secondDto , (Mo...
Read more
Image
Implementing gRPC Using Spring Boot and Gradle Background GRPC (gRPC) is a RPC framework pioneered by google later on made public and open source. GRPC has not been officially supported by Spring Framework, so far there are few community libraries that can work seamlessly with Spring Boot. In this article, I will use the lognet's grpc-spring-boot-starter. Project Structure Ideally, the proto files for gRPC is located in another directory, which will then be accessed by the gradle plugin to auto generate the required files.   Gradle Script The heart of gRPC enablement lies on the grpc boot starter, which includes few other tasks outlined as below. https://github.com/overtakerx/grpcbootdemo/blob/main/build.gradle Few important note: first you have to run gradlew compileJava for the auto generation to generate the files from the proto file, then you will need to rebuild the project for Intellij to recognise the auto-generated files. Full demo: https://github.com/overtakerx/grpcbo...
Read more

Spring Boot Reactive API

Image
 Spring Boot 2: Using Spring WebFlux & Tomcat for Reactive APIs Spring WebFlux is a somewhat new (since 2019) library from Spring Boot 2 that provides massive improvement in performance compared to the traditional synchronous calls. To quote the Spring documentation itself: Why was Spring WebFlux created? Part of the answer is the need for a non-blocking web stack to handle concurrency with a small number of threads and scale with fewer hardware resources. Servlet 3.1 did provide an API for non-blocking I/O. However, using it leads away from the rest of the Servlet API, where contracts are synchronous ( Filter ,  Servlet ) or blocking ( getParameter ,  getPart ). This was the motivation for a new common API to serve as a foundation across any non-blocking runtime. That is important because of servers (such as Netty) that are well-established in the async, non-blocking space. Further reading:  https://docs.spring.io/spring-framework/docs/current/reference/html/web...
Read more