Many of our projects at JUXT require the development of REST and GraphQL APIs. Customers want these delivered quickly, so separate front-end teams (whether from JUXT or not) can start iterating, and an integrated end-to-end system can take shape. But customers also want APIs in production to be secure, and there are some established standards today that can make this faster, and easier too.
Introducing Site
Site is a project, which includes a number of libraries from JUXT and elsewhere, that allows us to develop APIs quickly and securely. As with all our open source projects, Site was conceived from valuable observations made by our project teams working with JUXT customers:
- Many projects require the development of one or more stateful API services, either choosing REST or GraphQL. Most teams have adopted OpenAPI to design/document/communicate their APIs, and we have seen more teams move to a ‘design-first’ approach.
- The inability to quickly iterate on APIs harms the agility of front-end development.
- Authentication takes too long to build, even if this merely requires integration with a off-the-shelf authentication service.
- Access control is invariably a business requirement, yet often retro-fitted, late in the development process.
Design first
An API forms the contract between two parties, the client and the server.
Some teams generate an API from hints in the server code, or the API is merely the projection of internal data-structures within the server (such as a set of database tables). Rather, a good API should be designed carefully to meet the needs of client applications. If the API provides too little, it might not meet the requirements of all consumers. If the API provides too much, it will be more difficult and expensive to support that additional functionality over the long-term.
It is also critical that an API does not break compatibility with client-code written to consume the API service. If the API is designed ‘by hand’ (rather than generated from a server model), care can be taken to avoid introducing breaking changes to the API that would cause clients to stop working. This might not be necessary if the same development team are responsible for the code for both the client and server, but this is rarely the case. More often, the reason you publish an API in the first place is because you want to expose data and functionality to separate teams in your organisation, or beyond.
By far the most popular format for API design today is OpenAPI. Site allows us to upload API definitions in OpenAPI format and will implement the API dynamically, as if the back-end code had been generated directly from the API specification. Finally, if we choose to replace Site with a custom-engineered service later on, we can do so without changing the API that clients may be using.
Deliver, then reflect
During 2020 and 2021, we used Site successfully on a number of projects, making the necessary customizations as needed. We also added support for GraphQL, alongside OpenAPI, by integrating our grab GraphQL library.
At the end of 2021, after listening to the experiences of a number of successful Site deployments, I began to consider the question of access control. From the first release of Site, we’d had the ability to secure individual end-points. However, we wanted something more fine-grained, especially for securing individual parts of the result of a GraphQL query. For me, this became a year-long process of research and experiments ‘in the lab’. I focused on Site’s design as a fully-featured OAuth2 Resource Server and Authorization Server.
Technically, this means that client applications can be registered with Site. The registration process creates a client-id (and, in some cases, a client-secret). The client can then use these to acquire access-tokens, and these provide access to protected resources.
There are huge benefits to restricting access to APIs to authorized parties. It allows organisations to provide real-time access to data across teams without compromising on rules around who has access to what data. This is all-the-more critical for organisations that comply with SOC2, GDPR, CPA and more.
Find out more
Earlier this month, I gave an internal talk and demo to some JUXT employees about my work on improving access-control in Site. If you’re interested in API development and want to learn more, give it a watch. And if you have any questions or feedback, please feel free to write to me at mal@juxt.pro.
Finally, if you’re embarking on a new system development and APIs are important to your project, get in touch to see how JUXT could help you.
