API Design

Intro

NOTE: Work in process, documentation might not reflect latest changes or all available features #930

This documentation aims as an developer guidance point APIv2 development. For user/development documentation on the current API see Server API documentation (PDF) and User API documentation (PDF).

Code entry points

• Implementation of models: https://github.com/hashtopolis/server/tree/master/src/inc/apiv2
• Models common features AbstractBaseAPI: https://github.com/hashtopolis/server/blob/master/src/inc/apiv2/shared.inc.php
• Test suite: https://github.com/hashtopolis/server/tree/master/ci/apiv2
• Swagger UI: https://github.com/hashtopolis/server/tree/master/src/apidocs
• URL routing entry point: https://github.com/hashtopolis/server/blob/master/src/api/v2/index.php
• DBA Model generator (metadata): https://github.com/hashtopolis/server/blob/master/src/dba/models/generator.php

Design principles

• Database model is represented by /v2/api/UI/
• Helper function is represented by /v2/api/Helper/<Name
• Adaptation and Migration should follow an natural path for the user. Thus the 'APIv1' and APIv2' will exists next to each-other. No database models are changed, until the old API is deprecated-and-removed.

Code implementation

Abstract BaseAPI

• AbstractBaseAPI contains shared logic and dictated required API call required to implement.
• Type checking of input upfront to allow for better error messages on incorrect data input.
• Authentication is done via username/password login to request an 'token'. Tokens are valid for a specific set of time.
  • TODO: Document support for long-lived API keys.
• Requests and responses will be in unified JSON format.

Model API

• Model specific changes are part of modules and are exposed by implementation of abstract function definitions.
• Naming of Models and fields should follow database naming, how-ever during 'transition' from 'APIv1' to 'APIv2' mapping might be required.
• Permissions are modeled in CRUD (Create, Read, Update, Delete) principle on a per model basis. Their will be an mapping to support 'old' User/API permission schemes.
  • TODO: Implement #872

Helper API

TODO: Implement and document #871

• Permissions will be an combination of model CRUD permission, depending on models and actions of helper function.

Futher work

• 'expandables' are implemented in AbstractBaseAPI, how-ever they are specifically linked a DBA model, which could cause conflicts when names are re-used, thus needs to be moved.

References

• Automated APIv2 documentation (Swagger UI): https:///apidocs