Building business APIs without coding

How to build an API design system utilizing JSON Schema to make non-coders stay on top of development and prevent coders from re-inventing the API wheel over and over again.

APIs look and behave differently…

APIs come in different technologies and styles. Different companies are invested in different technologies and have developers of different background and knowledge. This is natural – in most industries there are no standards for APIs. API consumers just have to adapt to the different variants.

But APIs do not only differ between companies. They often differ between teams in the same organisation and sometimes the same team build APIs which seem totally unrelated. There may be reasons for this but it implies a heavy burden both for the maintaining team, who must split their focus between different solutions, and for the API consumers who needs to learn each API from scratch.

… but they do the same things

What I find interesting is that many APIs (the majority?!) do very much of the same things. REST APIs and others typically provide CRUD (Create Read Update and Delete) for some business object types (e.g order or customer) in one way or another.

A generic API flow coded for reading data

Implementations of “Read” typically follow a similar flow in code:

Note: “DB” does not have to be an database, it just represents the system which provides data (e.g MongoDB, Salesforce or just a file on the file system)

A generic API flow coded for modifying data

The flow for modification (CUD – “Create”, “Update” and “Delete”) can be coded as one flow which briefly looks like below:

Both the “Read” flow and the “CUD” flow can be further detailed and extended but the important point here is; they can still be kept as just two separate flows.

…and APIs can be coded without business knowledge

None of the two flows described above are specific to a special business object type – the flows are the same no matter if the business object to be handled is an order, a customer or anything else. This means the flows can be built agnostic to the business domain and be coded as components to be reused for any business object type.

Business domain logic as configuration – no coding

As the technical aspects of the APIs are built into the reusable components – the building of new APIs becomes a concern condensed to the specifics of the business domain. We do not need to re-invent the wheel of technical features like pagination, error codes or how to partially update an object in the database.

API design boils down to identifying which business objects should be represented in the API and creating the data structure and documentation of these business objects.

Implementation is just a matter of configuring the different decision points of the flows, i.e what should be accepted in each step of the flow to proceed to the next step.

An example of a generic component for the “CUD” flow exists in the API design system I am building which has:

Using JSON Schema for configuration

JSON Schema is a standard for validation of data and part of the OpenAPI 3.1 specification which means some basic JSON Schema knowledge will be good for anyone who gets in touch with APIs.

JSON Schema has proven to be a perfect fit for configuration of decision points in the API design system. A JSON schema defines constraints for a JSON structure and the outcome of a validation by JSON Schema is either true (valid) or false (invalid).

Example: JSON Schema for a person object which must contain "name" of type string and may contain "age" of type integer:

{
  "description": "JSON Schema for person",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

In case validation outcome is false, a JSON Schema validator can provide detailed information of what is wrong. This is useful for feedback to the user/client.

Example: Body the request body of {"age":20} is not allowed because "name" is required

400 Bad request

content-type: application/json
....

{
  "errors": {
    "/request/body": {
      "rejectedValue": {
        "age": 20
      },
      "violations": {
        "/properties/request/properties                 
         /body/required": [
          "name"
        ]
      }
    }
  },
  "valid": false
}

Configurable features

Someone who knows the business data (e.g a product owner or business domain expert) may define the business object type in JSON Schema format (“Validate and deserialize request body” in the picture).

The CUD component also makes it possible to define in detail with JSON Schema what a user/client is allowed to do (“Validate expanded request model based on permission” in the picture) and what user/client get in the response based on the users roles (“Filter API response based on permission” in the picture).

Valid combinations of current state (in DB) and new state (to be updated in DB) can be declared too (“Validate expanded state” in the picture). This is powerful and may be used to build finite state machines (see Build a state machine API with JSON Schema).

The CUD flow in this API design system will eventually be extended with more configurable features but the value of keeping it all together in one flow is big for maintenance of code and documentation as all efforts (e.g writing good test suites) can be focused.

Conclusion

Different APIs have many technical aspects in common and by coding similar APIs over and over again we end up with costly maintenance. Development gets slower when large parts of the API-building work require a lot of coding and everything that comes with that (e.g testing). Highly skilled coders don’t like repetitive work – we should use their precious time to create more value!

It is possible to build an API design system made up of technical components to make business domain experts and product owners more self-sufficient when it comes to building APIs. We have seen example of an API design system which makes it possible for non-coders to build full-fledged APIs by specifying JSON Schemas for pre-defined decision points in generic API code flows.

But..! An API design system will never be finished. The world is constantly changing and new business needs emerge. We need to evaluate our API design system continuously to understand it’s current limits in a way that makes us ready to swiftly extend it when a limit is reached. No need to worry though! There will be plenty of time for this valuable and proactive work now when coders do not need to re-invent the API wheel all day long… 😉

And last…

If you like the idea of building an API design system or if you are interested in using the one I described above – connect with me! 🙂

https://www.linkedin.com/in/niklas-eldberger-9b45b2a

niklas.eldberger@zuunr.com

/ Niklas