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

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

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

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

Understanding API Gateway Payload Mappings

Amazon’s API Gateway provides the facilities to map an incoming request’s payload to match the required format of an integration backend. API Gateway Payload Mapping API Gateway uses the concept of “models” and “mapping templates” to specify the mapping between the client payload and the server payload. Models A model defines the structure of the incoming payload using JSON Schema. The model is an optional, but not required, piece of API Gateway....

October 21, 2016 · 6 min · Kevin Sookocheff

Securing a Swagger API with OAuth2

In our previous article on Swagger, we defined a Player API modelling GET access to a Player resource. In this article, I show how to use Swagger’s security models to to deploy this API using an OAuth2 configuration. Swagger handles authentication and authorization using a combination of a “Security Definitions” Object and a list of “Security Requirements” Objects. Each of these definitions are applied at the top-level of your Swagger specification....

October 19, 2016 · 3 min · Kevin Sookocheff

How to deploy a Swagger specification to Amazon API Gateway using CloudFormation

Full sample code for this article is available on Github. Aamazon’s API Gateway supports the direct importing of Swagger specification files using CloudFormation rules. To do this, you have two choices. Injecting the swagger.json or swagger.yaml file directly into the Body field of the CloudFormation template, or uploading the swagger.json or swagger.yaml file to an S3 location and setting that location as the BodyS3Location field of the CloudFormation template. A minimal YAML template is listed below:...

October 18, 2016 · 3 min · Kevin Sookocheff

Designing a Swagger API

The goal of Swagger is to define a standard interface for describing REST APIs. In an ideal world, a Swagger definition for your API will allow both humans and computers to discover and understand your API. At it’s core, Swagger is a formal specification of an API. Surrounding this specification are a wide swath of tools to support creating documentation, providing client libraries, and managing API deployments. One of Swagger’s original goal was to provide a way to document an API in both a human and machine readable way....

October 12, 2016 · 6 min · Kevin Sookocheff