The False Dichotomy of Design-First and Code-First API Development

In creating a development workflow for releasing HTTP+JSON APIs, many teams settle on the API description and documentation standard OpenAPI. A natural conversation that takes place after settling on OpenAPI is whether or not you should develop your API using a “design-first” method or a “code-first” method. I believe that narrowing the discussion to these two extremes overly simplifies the discussion. Instead, I prefer to talk about API development as a continuum of development process that revolve around the prominence of the API description document in the process....

June 8, 2021 · 10 min · Kevin Sookocheff
Marching ants

The Cathedral, The Bazaar, and the API Marketplace

In The Cathedral and the Bazaar, Eric Raymond recounts the early years of Linux. Specifically questioning how the “part-time hacking of several thousands of developers scattered all over the planet” could create perhaps the most complex, functioning application in history. How could a “babbling bazaar of differing agendas and approaches” coalesce into a coherent and stable system without some form of centralized planning? The fact that this bazaar style seemed to work, and work well, came as a distinct shock....

December 11, 2020 · 8 min · Kevin Sookocheff

Marrying RESTful HTTP with Asynchronous and Event-Driven Services

Many organizations have multiple applications that are being built independently as a microservices-based platform. By its nature, a microservice platform is a distributed system running on multiple processes or services, across multiple servers or hosts. Building a successful platform on top of microservices requires integrating these disparate services and systems to produce a unified set of functionality. It is naïve to think that we can only choose one communication style to solve all problems; if integration needs were always the same, there would be only one style and we would all be happy with it....

November 24, 2020 · 13 min · Kevin Sookocheff

Overambitious API gateways

In a microservices architecture, an API gateway can help address a number of challenges: providing a stable endpoint for clients to call, allowing an easy process for releasing new endpoints, or handling SSL termination on behalf of services, to name a few. So how do we decide what features of an API gateway to adopt, and which to leave behind? This article highlights the key functions that an API gateway can provide, suggests the scope of problem that API gateways are well-suited to solve, and cautions against the features that make API gateways too ambitious....

February 22, 2019 · 7 min · Kevin Sookocheff

Uploading Large Payloads through API Gateway

API Gateway supports a reasonable payload size limit of 10MB. One way to work within this limit, but still offer a means of importing large datasets to your backend, is to allow uploads through S3. This article shows how to use AWS Lambda to expose an S3 signed URL in response to an API Gateway request. Effectively, this allows you to expose a mechanism allowing users to securely upload data directly to S3, triggered by the API Gateway....

May 10, 2017 · 6 min · Kevin Sookocheff

Comparing Swagger with Thrift or gRPC

I’ve been asked recently, what’s the difference between Swagger and Thrift (or gRPC)? Although they look similar, they solve fundamentally different problems. Let’s look at the differences. Swagger At the most basic level, Swagger is a REST API specification language. The great part is that there is an entire ecosystem of tools built around this specification language to support API design, client and server code generation, and interactive documentation. Key Features REST + JSON API framework....

February 9, 2017 · 3 min · Kevin Sookocheff

Optimistic Locking in a REST API

In a REST application, it’s often the case that several clients might interact with a single resource, each holding a copy of the resources state. At any point in time, these client’s understanding of resource state may differ from each other or from the server. Without some way of realigning resource state, changes requested by a client based on an out-of-date understanding of resource may have undesired effects, from repeating computationally expensive requests to overwriting and losing another client’s changes....

December 21, 2016 · 4 min · Kevin Sookocheff

Checking for null in an API Gateway transform

Amazon’s API Gateway provides the ability to transform a response from an endpoint into a different format for return to the client. One thing I wished to accomplish with this was to return a value to the client, only if it was set in the response. Essentially, I wanted to check for the existence of a JSON property in the response, and react accordingly. The solution was not obvious to me, and this post serves to record that solution for posterity....

December 19, 2016 · 1 min · Kevin Sookocheff

Effective Cache Control

The web supports a global network of billions of devices and users, and a key component of this support is effectively caching frequently accessed data along the request-response path. One of the key benefits in adopting a REST architectural style for your system is being able to leverage this existing infrastructure, taking advantage of the billions of dollars of investment already made in the web, and promoting loose coupling, performance and scalability....

December 19, 2016 · 10 min · Kevin Sookocheff

Configuring REST-assured for Amazon API Gateway

As part of testing our Amazon API Gateway deployment, we set up JUnit tests to run automated Swagger/OpenAPI validation using Swagger Request Validator and REST-assured. This allows us to write simple tests in a fluent style, with automatic validation that requests and responses match the Swagger API specification deployed to API Gateway. given() .log().all() .filter(validationFilter) .when() .post("/oauth2/token") .then() .assertThat() .statusCode(200); Out of the box, REST-assured does not work with Amazon’s API Gateway endpoints using Java 8....

December 13, 2016 · 2 min · Kevin Sookocheff