Zwannah API Structure Specification (Actors-Supporters Arrangement)

Introduction

The Zwannah API Structure (Actors-Supporters Arrangement) Specification specifies how files in an API should be arranged to enhance security, maintainability, and organization.

In ZAS, an API could be any backend that powers some set of frontends. For example, an app that has mobile, desktop, and web application frontends running on a single backend. The ZAS can work with APIs that use routing to make public their resources. The routing logic should be placed in the `actors` directory since that’s where HTTP requests/responses are allowed.

Why ZAS?

There are many Frameworks for creating APIs such as Laravel, AdoniJs, etc. However, these frameworks handle requests in a container-based fashion. This can lead to resource consumption, sometimes unnecessary, for example, memory consumption. An API can be developed in such a way that the resource consumption is based only on the process to generate the response for a given request. For example, a PHP API that uses file paths as routes doesn’t need to boot up a router and hence the request goes directly to the script that should handle it. This mean, the request only consumes as many resources as it needs. The ZAS Specification is especially suited for such a scenario, allowing non-container-based APIs to be developed in an organized and secure way.

ZAS Naming Conventions

1. directory names: All words in directory names should be lowercase and separated by dividers such as underscores or dashes. E.g engine-client.
2. filenames: all file names should be lowercase and words separated by dividers such as underscores or dashes. E.g. product-category.class.php
3. extensions: the file extension should reflect its purpose. for example, “user.php” that holds a user class code should be named “user.class.php” or any proceeding extension as chosen by the organization before the language’s extension. For example, “user.class.php” could be “user.cls.php”.

Terminologies

• process: consists of one or many files to perform a common function.
• Side-effects: include but are not limited to: generating output, connecting to external services, modifying system-wide configurations, emitting errors or exceptions, modifying global or static variables, reading from or writing to a file, and so on.

Overview

All rectangles with rounded corners are processes, circles indicate a boundary between left and right branches, and others are directories.

Structure

1.0 API (root directory)

The API directory is the root directory from which the structure begins. If the API is deployed, the exposed directory doesn’t necessarily have to be the API directory. It could, and should mostly be the api/actors/foreground directory. This ensures that no request can be made to the supporters without further security on “apache web server”; This directory could be called any name.

1.1 setup (process)

The setup is a process that is responsible to set up dependencies used by the lower processes. For example, in PHP, you want to include the vendor autoload in this process. Other Includers such as your own autoloading should be done here. This process could be a single file or multiple files. However, this process will be included in every (process) below it (your own initiative).

2.0 actors (directory)

Actors directory contains all processes (files) that can interact directly with clients. These are the processes that perform the work on the server. All HTTP requests are made to processes in this directory. An HTTP request should not or cannot be made to processes in the supporters directory. You should set up security rules or only expose the actors directory to HTTP requests. All actors must have a side-effect.

2.0.1 authenticator (process)

The authenticator process checks if the request is authenticated and updates a global state variable accordingly. This state variable could be anything. For example, it could be a userId whose default is 0. If a user is logged in, then it is set to the user's ID. This global variable, as the name suggests will be available to every process below it. The authenticator here should not be used to block access to the service, it should only be used to update the state of the request. Let the lower processes handle this state accordingly. For example, a login process will check if the userId is not 0 and respond with an "already logged in" message. However, for an update process, this state will lead to the response "not logged in... or blah blah blah.. with code 403".

The authenticator must include the setup process. For example, if you have a database-managed session, you should ensure that when you create a database manager object in the authenticator to query the database, you don’t get a “Class not exist” error. This is why the Authenticator needs the setup processes.

2.0.2 foreground (directory)

The foreground directory holds the processes that interact through HTTP requests. Their executions are initiated but not necessarily terminated by an HTTP request. This means every file that does some work for the client on the server and needs HTTP requests to be initiated should be placed in this directory. If a router is needed, it should be placed in this directory.

2.0.2.1 process groups (directories)

At this level, processes that perform similar functions should be put together in a single directory. This will make development faster as every process directory can have its own master Includer which will include everything from the root setup to the authenticator or the state of the requests. This is open to interpretation and further extension.

In an MVC framework setup, Controllers can be placed in this directory. This will assume that the router is placed in the foreground directory.

2.0.3 background (directory)

As the name suggests, this directory holds processes that run in the background. HTTP requests cannot be made to processes(scripts) in the background directory. All the processes in the background directory must either be initiated by a script in the foreground directory or the server itself. For example, a background script that verifies payment can be deployed by a foreground script to continuously check if the initiated payment (by the foreground script) was completed successfully. Also, scripts that are run by cron jobs are placed in this directory.

The communication between the foreground and background scripts are made through CLI. This means every script in the background folder is a Command-Line Application. With this in mind, you can have a C++ or Java program in the background directory that can be called from a foreground PHP file with all the required arguments.

2.0.3.1 setup (process)

The setup process is responsible to set up the necessary dependencies required to run files in the command line. This is because some files will be unable to use the general setup at the top. For example, a C++ executable won’t use a PHP dependency. Here, you can also check if the request is actually from a Command-Line, not some HTTP request.

2.0.3.2 authenticator (process)

The authentication process is to set up the authentication status of the Command-line call. Since arguments are passed as strings, this authentication process will update the call’s state so that the script being called can handle the call’s authenticated state accordingly. For example, if a script is to be called by a cron job, you want to pass arguments that will render the call authenticated to the script. This helps security because not any command line call from the terminal will be honored by the script.

2.0.3.3 process groups (directories)

This is the final level where processes are grouped into directories based on whether they perform functions to achieve a common goal. for example, notifications scripts will be placed in the notifications folder. This is open to interpretation and further extension.

2.1 supporters (directory)

The supporters directory holds all the processes that are meant to support the actors. All supporters cannot interact with clients directly. They must be called from an actor process. For example, a supporter can be a class, trait, interface, configuration, schema, etc. The Rule is, that supporters cannot interact with clients directly. This makes it clear that the supporters are scripts that could cause side effects whereas actors must cause side effects.

2.1.1 supporters groups (directories)

These are groupings of supporters that provide similar support to actors. For example, a class should be placed in the classes folder as well as an interface in the interfaces folders. This is open to interpretation and further extension.

GitHub: https://github.com/levizwannah/zwannah_api_structure_spec