Semaphore

Last update on 2024-02-14 at 5:07:11 PM

Semaphore is an application that sits between two other applications: a business system on one side and a service on the other. Its aim is to ease the effort and the cost of building a REST API for every service needed by a business system, and vice-versa. The primary use case and incentive is to be an intermediary between the business system of a local government and a "software-as-a-service" solution.

It works by using any API the service might have, including the API of an app that the service might use as frontend, and exposing it according to a consistent and well-known API for the business system, while implementing any authorisation and authentication the business system might require. It works like a conduit, or, indeed, as a semaphore, ie: a system that does no more than transform one writing system to another.

A little more about the "why"

Using external software tools is a good way to outsource specific needs of your organisation. Of course, using external tools implies sharing data, and automating data sharing is the go-to way of saving time and money. But sharing data automatically with the external tool means implementing a REST API for each. This is inefficient, challenging to organise, time-consuming and costly.

Semaphore is an effort to mitigate this problem by offering an application that exposes a simple REST API to business systems wishing to use such an external software tool, while implementing any authentication and authentication methods needed to ensure safe and secure communication of data.

It is designed to be the "go between" between any external software tool that has inspections as its knowledge domain. In other words, it "translates" between the data structure a business system can expect to send to and receive from the external software tool and the external software tool itself, which might expose a more idiosyncratic or very domain-specific API. Which might even be an existing API used by the external tools' user interface. The point being that the business system will have nothing to do with such idiosyncrasies: that is the job of Semaphore to resolve.

The basics

Listed below a a high-level overview of the data flow:

A business system can send data to Semaphore in order to enable the inspection of a an approved permit on the external software tool. In response, the business system receives a unique identifer with which to do follow-up requests for that permit.
The business system can request updates on the inspection, ie, the status of the inspection, but also many other aspects, such as date started, intermediary reports in pdf or docx
Finally, the business system can request and receive the final report when the status of the inspection is closed.

Details

Our aim is to follow the data structure of the business systems as much as possible, however, at this point in de development of this product we are still in the learning phase. So, to start, we have identified key categories that we think are useful, and indeed have seen in both business systems and external tools.

Object: to be seen as the physical object that is to be under inspection. This can be an existing building, a building site, or any other piece of real estate.
Subjects: a list of stakeholders, ie, people that are either responsible for the Object or have tasks related to the Permit
Permit: the case number which identifies a permit, an identifier for the category of the inspection, any documents related to the permit, and an identifier of the person changed with the inspection.

{
  "cases": [
    {
      "object": {
        "address": "Some Address 65",
        "place": "Amsterdam",
        "coords": "52.99999, 4.2222"
      }
    },
    {
      "subject": {
        "stakeholders": [
          {
            "name": "somebody",
            "role": "Architect",
            "address": "none"
          },
          {
            "name": "else",
            "role": "permit requester",
            "address": "none"
          }
        ]
      }
    },
    {
      "permit": {
        "case_number": "12344566789",
        "finding_list_code": "EO1",
        "inspector": "somebody@example.com",
        "documents": [
                    {
                        "name": "humanised name 1",
                        "url": "https://example-business-system.com/blueprints/dummy1.pdf"
                    },
                    {
                        "name":"humanised name 2",
                        "url": "https://example-business-system.com/blueprints/dummy2.pdf"
                    }
                ]
      }
    }
  ]
}

A simplified POST request to create an inspection via Semaphore

Documentation

Semaphore is in the very first stages of development (0.0.1). The documentation is only meant to give an idea of the scope, certainly not meant for actual use in production.