|
BAOBAB
|
|
|
BAOBAB
|
|
BASALT is the REST API and extension framework of the Rift Valley Platform.
Think of it as "part one" of the CONTROLLER layer of the MVC Pattern. "Part two" will be provided by the client SDKs.
ANDISOL is the "public face" of the MODEL layer.
BASALT allows the creation of "REST Plugins." These are fairly simple PHP executables that are placed in known directories.
BASALT matches these to the plugin parameters in the REST URIs, and routes REST HTTP calls to the designated plugins, returning the result of the plugin processing.
REST Plugins are simple subclasses of the A_CO_Basalt_Plugin class, and are used in a very basic stateless fashion; inheriting utility functions from the abstract base class.
BASALT REST Plugins only have two public abstract methods, and one protected method:
A_CO_Basalt_Plugin::plugin_name
This is an extremely basic method that simply returns the name of the plugin for use by the main BASALT system.
A_CO_Basalt_Plugin::process_command
This is the method that actually processes the REST command. The (possibly logged-in) ANDISOL object is passed in, along with the HTTP method, response type, and any further commands and/or query parameters.
The method will respond with a string to be returned, reflecting the result of the requested command.
This is a very simple method that simply returns the POSIX path to the XSD file fragment for this plugin. This schema must be comprehensive for ALL possible XML responses from the plugin.
BASALT will include a few "built in" plugins, but the implementor of the server can write and install more plugins, giving a very powerful facility for managing REST interactions.
BASALT expresses a pseudo-REST API access to the Rift Valley BAOBAB server. It is not a "true" REST API, in that the PUT and POST methods are handled differently than "true" REST.
The server can be configured to require that all REST access be done as TLS (SSL/HTTPS), and uses a "server secret/API Key" method of authentication.
BASALT's REST API implements the following methods:
This is the classic "show me the money" method. It can be easily expressed in a standard browser URI. Use this to fetch resources (like doing searches). You do not have to be authenticated to use this method.
This is used to create new resources. You must have an authenticated login to use this.
This is used to update/modify resources. It can be used where only the changed portion of a resource is provided. You must have an authenticated login to use this.
This deletes a resource. You must have an authenticated login to use this.
BASALT's REST API can return data in the following formats:
This is the most common "lightweight" protocol used for access. It is well-supported by most libraries and ECMAScript implementations, such as JavaScript, and other programming languages.
This is a strictly-defined protocol that is common for a lot of semantic implementations. XML output exactly correlates to JSON. Additionally, all XML output must validate to a published schema.
This is the validation schema for the XML output. Each plugin must publish a schema to validate its XML against.
Simple String
This is only returned by the login operation. The API key is returned as a simple UTF-8 string.
In order to log into the BAOBAB server, you must call it once with a basic username/password combination, in a simple GET call. The server can be configured to require that this always be TLS (SSL/HTTPS).
Once you have successfully logged in, the server will respond with a simple text resonse, containing a timed API key. You will then place this API key in the password field of the HTTP authorization header of subsequent calls (the Server Secret goes in the user field).
Example in a PHP cURL implementation (where "$api_key" contains the string returned from the login call, and "$server_secret" contains the server secret, provided by the server administrator):
curl_setopt($curl, CURLOPT_USERPWD, "$server_secret:$api_key");
However, this won't work with FastCGI, so we also have the option to attach them as URI query arguments:
{GET|PUT|POST|DELETE} http[s]://{SERVER URL}/{RESOURCE PATH}?login_server_secret={SERVER SECRET STRING}&login_api_key={API KEY STRING}
The API key is timed with a fixed clock. The time is determined by the server, but the default is 1 hour (60 minutes) for standard logins, and 10 minutes for the "God" login (the superuser). The clock is not reset during use, so it is an absolute time limit. Once you log in, the clock starts ticking, whether or not you access the server afterwards.
When you call the REST API, you will do so in the standard fashion, where you define the method (HTTP 1.1 header), and specify the resource in a URI, which can include query data.
Initial Login Call:
{GET} http[s]://{SERVER URL}/login?login_id={LOGIN ID STRING}&password={PASSWORD STRING}
The {SERVER URL} is the URL path that specifies the BAOBAB server REST entrypoint (like "example.com/rest_api/baobab/entrypoint.php").
In this instance, you directly call the REST entrypoint, specifying only "login" (which also means that you can't create a plugin named "login"). The query parameters are:
The query parameters are:
login_id
This is the user's login ID (a simple string)
password
This is the cleartext password for that login.
This is only called once, and cannot be combined with any other commands. The only operation permitted is a simple login.
The response will be a simple string. This will be a 32-character (or 40-character, for "God" logins) random token that should be applied in the username AND password sections of the HTTP authorization header header of subsequent calls.
Logout Call:
{GET} http[s]://{SERVER URL}/logout[?login_server_secret={SERVER SECRET STRING}&login_api_key={API KEY STRING}]
This is a call that should be made while a valid API key has been assigned to a user. It should be made with the user's valid API key in the HTTP authorization header, or auth parameters, and will terminate the API key, requiring subsequent calls by the same user to perform another login.
Use Auth Params Test:
{GET} http[s]://{SERVER URL}/use_auth_params
This simply returns 1, if the caller should send authentication as query parameters (for example, if the server is using FastCGI), or 0, if Basic Auth headers are sufficient.
Standard REST Calls:
{GET | POST | PUT | DELETE} http[s]://{SERVER URL}/{RESPONSE TYPE}/{PLUGIN}/[{COMMAND[S]}][?][{QUERY PARAMETER NAME}[={QUERY PARAMETER VALUE}]]
{RESPONSE TYPE}
This is "xml", "json", "csv" or "xsd". If it is "xsd", then commands and query parameters will be ignored. The response will be an XML Schema document. "csv" is a special case for "God-Mode-Only" backup requests.
{PLUGIN}
This is the all-lowercase name of the BASALT Extension plugin. There is a BASALT "virtual plugin" called "baseline". This will return a list of available plugins, if called directly. (Example: http[s]://{SERVER URL}/{RESPONSE TYPE}/baseline/)
{COMMAND[S]}
This represents a single command (or a series of commads, which are expressed as "command1/command2/command3/" etc.) for the plugin. These follow the /{PLUGIN}/ URI component.
If you will be providing query parameters to the REST call, then these are attached after the question mark. {RESPONSE TYPE} and {PLUGIN} are required. The other elements are optional, and plugin-dependent. Each plugin will define its own REST query structure that is parsed after the {PLUGIN}.
There is facility for logging. You can define a log handler function in the configuration, which will be called upon successful instantiation of an ANDISOL instance. This is not meant to replace the standard HTTP logs from the server, but is focused on the BAOBAB server, and will report the current logged-in user.
Logging is not enabled by default. It should be noted that it is possible that logging can have legal, technical and resource limitation issues. You should make sure that there are no issues with logging before enabling it.
ANDISOL is the "public face" of the lowest levels of the Rift Valley Platform. It encapsulates the model (database or server connections), and provides an object-based, functional model to the implementation layers.
COBRA is the security administration toolbox for the Rift Valley Platform. It is only available to logged-in users that are "manager" users; capable of editing other users.
CHAMELEON is the "First Layer Abstraction" from the data storage and retrieval. It implements a few higher-level capabilities, such as collections, users and places.
BADGER is the "First Layer Connection" to the data storage subsystem. It uses PHP PDO to abstract from the databases, and provide SQL-injection protection through the use of PHP PDO Prepared Statements.
© Copyright 2018, The Great Rift Valley Software Company
LICENSE:
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The Great Rift Valley Software Company: https://riftvalleysoftware.com