An iterative approach to Data and API management

Jargon (https://jargon.sh) is a platform for designing modern and beautiful APIs.

In this next part of my ongoing series on Jargon, which you can read in full here, I’ll be going over how all of Jargon fits together to deliver an iterative approach to managing Data Models and APIs.

Here’s an overview of what we’ll be going over in this post:

Each Jargon screen plays a role in helping to untangle your data

It all starts with a plan — A Town Plan

A Jargon Town Plan shows how your information and APIs will be structured

Although you can jump right in and create a Domain right away in Jargon — a Town Plan will help create cleaner, modular and more reusable domains. Town Planning is a fast and light weight way to play around with how your information will be architected. Are you going to put all your client information into one Domain, or are wholesale and retail clients different enough to have multiple Domains? By trying out these options, you can get a better feel for how different parts of your architecture can evolve and how they will be governed. Here’s an in-depth post on Town Plan Driven Development that will teach you about this process in more detail.

Iteratively start creating the Domains

Jargon uses a very simple textual language to model Domains, and an interactive diagram view where you can layout your models for easy reading.

Now that you’ve outlined how your Domains should be layered and organised, it’s time to start creating them. Looking at your Town Plan, you should be able to work out which order to start in — ideally starting with a Domain that doesn’t depend on any others. It’s ok, and generally a pretty good idea, to start small and don’t sweat the big stuff for a while. If you get going and then realise that you’ve made an error — don’t worry about it. Until you’ve made a release of your Domain you can rename and reorganise it. Just go back to your Town Plan and update it with your new findings. Here are the guides on Creating Domains and Modelling Data, in case you need a refresher.

Generating artefacts, like OpenAPI specifications from your Domains

Jargon generates API specifications from your Domains, following pick-and-choose templates that you can customise to suit your project’s needs.

In Jargon, the Domain is king — everything that you work on is either a Domain, or a representation of a Domain in another technology — such as API specifications or state lifecycles. Following this approach means that all of the artefacts that depend on a specific version of a Domain are kept together with that Domain and are versioned along with it. You also don’t need to wait to create a Release before you can start working on your artefacts — so long as your Domain has everything it needs, including all its imports. For API specifications Jargon follows a template-driven approach that applies consistent technical details, like security headers and other parameters. Each API is derived from the data model of your Domain, and some specific traversals through your model to represent the API Paths you want exposed. It’s all explained in quite a bit of detail in our guide to creating OpenAPI specifications.

Releasing and Importing Domains

Imports in Jargon are bi-directionally traversable, meaning you can see all the Domains that import yours, and all the Imports a Domain has.

A key benefit of Jargon is that you can reuse the work that you’ve done, or the work of complete strangers, to your advantage. This happens by Importing one or more released Domains into yours and using their data models instead of creating them again. Jargon makes it easy to search for and find Domains if you aren’t sure what’s available — so be sure to take a look around before diving too deeply into creating a Domain from scratch. Jargon uses a style of versioning called Semantic Versioning (or SemVer), which you really should take a look at if you’re not familiar with it. An important side-effect of following SemVer is that you really shouldn’t get hung-up on specific version numbers (such as the seemingly all important v1.0.0) — and focus instead on iteratively and routinely releasing your Domains when they have something of value to share. Following this approach means that you can incrementally release each of your Domains when they have enough structure to help flesh out others. Here’s the guide on how to Create Releases and Import Domains.

Back to the Town Plan

Once you start to create Releases for your planned Domains, you should go back to your Town Plan and replace the proposed Domains with their released versions. Doing this will convert your Town Plan from a planning artefact, to an interactive view that shows the dynamic relationships between your Domains and their imports. Whenever a newer Release of a Domain becomes available, the Town Plan will let you know. Maybe a newer version of a Domain you’re using isn’t something you’re interested in — but by clicking through to it from your Town Plan will let you look at it’s release notes, and doing a comparison between the version you are using and the latest will show you all the changes that you might want to take onboard.

Ready to give an iterative approach to API and Data Management a try?

Jargon is free for individuals to use, and you can get started right away. Free accounts can create an unlimited number of public Domains and all of the artefact types.

Jargon also supports collaborative team-based development and governance of Domains, following a per user, per month pricing model.

Thanks for following along, and drop by and give Jargon a try for your next Data modelling or API project.