Advanced API Data Modelling Techniques with Jargon

A simple Domain model that conveys quite rich concepts

By visually designing the data that your API will use, Jargon lets you apply some advanced modelling techniques that help you clearly describe how everything hangs together, letting you tell a clearer and business-oriented story.

Here is the Domain and rendered API Specification that we will be going through in this article. There’s quite a lot of detail that I won’t cover here, so head on over and take a look if you would like some more information.

For each technique, I’ll give you an overview of what it does, how you do it, and what impacts it has on the generated API specification.

Here we go:

References

When one class uses an Entity as a property, Jargon can refer to this Entity via its key. Think of it like a primary key in a database, except you don’t need to specify what it is. Jargon will infer it based on how you’ve modelled your Domain.

Using References allows you to loosely couple your classes together — especially useful if the property’s class is in another Domain — while still conveying the business relationship of the Domain, which is what Jargon is all about.

This relationship now reads like: A Person can have a Vehicle.

Not like: A Person can have the license plate of a Vehicle — although that is how it is implemented.

A reference relationship between the Person class and the Vehicle class

In this example, Person has a property called vehicle. It’s been marked as a reference (which you can read from the diagram with the <<reference>> tag) by adding the [jargon.reference] key-value pair to the definition of Person.vehicle:

The business definition, with [jargon.reference]=true

Jargon adds relevant notes to the API specification to let consumers know exactly what’s going on:

The API specification, stating that the vehicle property is actually the licensePlate key of Vehicle

Abstraction

Superclasses in Jargon are concrete by default— meaning that they can be the target of API calls. Marking a superclass as abstract forces consumers to provide one of the subclasses instead.

Making Pet abstract means that there really isn’t a Pet within the API, and that it’s merely a convenient way to express Domain rules:

The model reads like: A Person can have multiple Pets

Not like: A Person can have an array called pets, where each element in the array must be either a Dog, Cat or Elephant.

The Pets superclass has been marked as abstract

Pets has been marked as abstract by adding the [jargon.abstract] key-value pair to the definition of Pet, and have had the <<abstract>> marker added to the diagram:

The business definition, with [jargon.abstract]=true

The API documentation clearly relays this concept to consumers:

The API Specification, showing that Pet is really one of Dog, Cat or Elephant

Aggregation

When classes have lots of properties, it can be hard to keep a handle on the ones that naturally belong together. Aggregation allows you to manage groups of properties as seperate classes, and then flatten them all out into one big class.

The Domain model, showing that VehicleDetail is aggregated into Vehicle

This model reads like: Vehicles have information about Registration and other VehicleDetail

Not like: Vehicles can have numberOfWheels, numberOfDoors and Registration information.

Aggregation is a concept that belongs to the usage of a Class, and not on the Class itself. The digram shows this by adding the <<aggregation>> marker on the property that has been aggregated, and is enabled with the [jargon.aggregation] key-value pair:

The business definition, with [jargon.aggregation]=true

Aggregation behaves as you would expect: to inline all the properties that have been aggregated alongside all other properties of the Class:

The API Specification, showing that the properties from VehicleDetail have been inserted into Vehicle

Deprecation

Marks the class or properties as deprecated, and adds a note to say they may be removed in the future. This helps consumers know what things are going to change in the future.

Deprecation also helps other modellers by informing them that they’re using concepts that have been deprecated. Jargon does this in a couple of ways:

In the text of a Domain that uses deprecated things:

Note the yellow warning markers — that means Jargon has added warnings

As warnings on the Domain:

Jargon’s errors and warnings dialogue, showing the warnings for using deprecated things

And visually on the Diagram:

The Domain model showing usage of deprecated properties, which have been visually struck out

It also flows through to the API specification, so your API consumers are aware:

The API Specification showing that how deprecated properties are displayed, along with Jargon-specific text that has been added

Classes and Properties can be marked as deprecated with the [jargon.deprecated] key-value pair:

The business definition, with [jargon.deprecated]=true

Wrapping up:

So that’s how you can enrich your APIs and Domain models with some more advanced and formal modelling techniques.

The Domain Model and API Specification for this article is available in the public Jargon instance.

If you have any further questions about advanced API data modelling tehniques, you can:

• check the Getting Started Guide
• leave a comment below
• raise an issue at the jargon issue tracker GitHub repository
• Sign up for a free Jargon account and try the techniques out for yourself.