Generating JSON Web Token Assertions

A JWT (JSON Web Token) is a type of security token that is used to securely transmit information between parties. It is a compact and self-contained way of representing claims to be transferred between two parties. Many API providers require you to generate a cryptographically signed JWT assertion that includes the authorization you are requesting from the server. If the server accepts the assertions you are claiming in the JWT, it will respond with an access token granting access to the API....

May 11, 2023 · 8 min · Kevin Sookocheff

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

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