Api

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. ...

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. ...

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. As I learned my way around, I worked hard not just at individual projects, but also at trying to understand why the Linux world not only didn’t fly apart in confusion but seemed to go from strength to strength at a speed barely imaginable to cathedral-builders. ...

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. In reality, a single service can can communicate using many different styles, each one targeting a different scenario and goals. This challenge is what brings me to the topic of this blog post: when and why do we use different communication standards? ...

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. ...

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. ...

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. JSON requests and responses. Code generation. Documentation generation. Thrift Thrift is a software framework for supporting RPC. An interface definition language is used to describe your system in terms of data types and interfaces, the Thrift compiler generates client and server code that match your definition, and the Thrift library handles serialization and transport. ...

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. ...

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. Attempting to use it results in a handshake error when connecting to the API Gateway endpoint. ...

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. By providing a model, you make it easier to define the upcoming mapping template that actually does the transformation between the client and server. ...