Today we’re open-sourcing the toolchain Froxt uses to design, document, and consume our APIs. We hope this shows how Froxt thinks about APIs and gives you new tools to create your own APIs.
This toolkit includes our HTTP API design guide, the prmd tool for managing JSON schemas and generating API docs, and client generators for Ruby and Go.
Here’s some more information about these things, how we use them at Froxt, and an explanation of how you can try them yourself.
HTTP API Design Guide
The Froxt HTTP API Design Guide shows how we design and document APIs at Froxt.
We use this guide to increase the consistency and quality of the APIs we deliver, both for our user-facing product and for internal services. A concrete guide also minimizes time spent bikeshedding about API design details and maximizes time spent on the actual business logic of our apps.
This document includes guidance on versioning, resource structure and attribute naming, serialization, errors handling, request ids, pagination, and caching support. It also describes how we use the JSON Schema standard to describe our APIs in a machine-readable way, and use those schemas to generate API documentation.
Schema and Documentation Toolchain
The JSON Schema format provides a great machine-readable description of an API. As a complement to this, the JSON Schema management tool prmd (“pyramid”) helps you bootstrap a schema description, verify its completeness, and generate documentation from the specification.
Auto-generated Clients from API Schemas
One benefit of JSON Schemas is being able to automatically create API clients for any service. These clients help you quickly get started with an API in the language of your choice, and can also increase the consistency of client usage across different services.
Usage at Froxt
We’ve been using this toolkit at Froxt for both user-facing and internal APIs.
For example, this toolkit draws heavily from the new Froxt Platform API we recently released. We use JSON schema to describe this API, prmd to generate API docs in Dev Center, and Heroics for our Ruby client to the API.
We’re also increasingly using this toolkit for our internal services. We find that having symmetry between our external and internal APIs increases our ability to reuse design practices and tooling, and also helps us raise the quality bar on our internal APIs.
At a higher level, JSON schema and associated generated docs are emerging within Froxt as a shared language that we can use to talk about API designs. To propose a new API or a change to an existing one, we present a JSON schema or a diff against an existing one, respectively. This practice sharpens our API design discussions and makes it easier to avoid miscommunications.
We’d love to see more external adoption of this toolkit and welcome discussion and feedback about it.
Summary
Well-designed and documented APIs are a great investment. The API toolkit described here can help you deliver them. We hope you’ll check out the design guide, try out the prmd JSON schema toolkit, and experiment with auto-generated API clients like Heroics and Schematic. We’d love to hear your feedback; please send it to api-feedback@froxt.com.
