Hacker Zone
tools made for hackerspaces

How to write a Space API app?

It's very straightforward to create a new app to be integrated with spaceapi.net. This guide will help you to dive into the necessary details and to get your first app quickly done.

Getting started

Get the app framework and just follow this guideline for the setup.

If there are still questions after reading the guideline, just ask @slopjong who developed the whole website.

Create the directory structure

In the app directory create the files as shown below.
 skeleton
    |-- app.php
    |-- css
    |   `-- style.css
    |-- meta.json
    |-- scripts
    |   `-- appname.js
    `-- templates
        `-- appname.html
FileRequiredDescription
app.php yes This file contains the main code to inject the content in the page as well as necessary javascript and stylesheets. In this file you define a class which must inherit from the Page class.
meta.json yes This file contains meta information about the app itself but also about the developers and their home hackerspaces. Some of these information are displayed in the footer.
style.css no The place where you should put all your CSS rules. The template file or app.php should never contain any rules. This will allow your browser to make use of the cache on your next visit.
appname.js no If your app needs some javascript put it in this file for the same reason as you put your CSS rules in style.css. Browsers will cache it. Additionally this allows us to make use of the Content Security Policy.
appname.html no If your app consists a lot of HTML you are encouraged to outsource it. Add placeholders to your template file appname.html and use str_replace in app.php to render the actual app content. Afterwards call $this->addContent() in app.php with the rendered template as the parameter.
Replace appname with something more meaningful, maybe your app name?
There are no strict rules how to structure your app but we recommend to use the one above. You are also given full freedom of how to template. Feel free to use your own templating style or to use a framework such as Twig, CodeIgniter or anything else with a small footprint.

File contents

meta.json

{
    "App": "My app name",
    "Description": "Little description of this app.",
    "Authors": [
        {
            "Name": "John Doe",
            "Nickname": "johndoe",
            "Hackerspace": "johndoespace"
        }
    ],
    "License": "",
    "Created": "29.7.2013"
}
The field Authors is an array of objects, one object for each contributor. So if multiple people are working on the app, list them all.

app.php

<?php

if(!defined("APPSDIR"))
die("Direct access is not allowed!");

// inject your stylesheet if you need it
$page->addStylesheet("css/style.css");

// inject your javascript if you need it
$page->addScript("scripts/appname.js");

// you can use a heredoc or a nowdoc to write your page content
$html = <<<HTML

    <section>
    <h2>Hello World!</h2>
    It's very straightforward to create a new app. Just have a look at the documentation or at existing apps.
    </section>

HTML;

$page->addContent($html);

// add more content, this time by loading a template file
$html = file_get_contents("templates/appname.html");
$page->addContent($html);

Placeholders

You can use the following placeholders in your HTML.
PlaceholderDescription
%SITEURL%This placeholder will be replaced with spaceapi.net.
%APPDIR%This value will be replaced with the full path to your app directory..

PHP constants

Below are some constants that are available. You might not need them if you're using the API described in the next section.
ConstantDescription
SPECSDIRThe directory with the specification files, one for each version. These are all JSONs and are provided throuth URLs like spaceapi.net/specs/0.13 while 0.13 is the version number, leaded by a zero and a dot.
 specs
   |-- changelog
   `-- versions
          |-- 11.json
          |-- 12.json
          |-- 13.json
          |-- 8.json
          `-- 9.json
If you need a specs file, just execute something like $specs = file_get_contents(SPECSDIR . '13.json');.
DIRECTORYKeeps the directory. With file_get_contents(DIRECTORY) you read the directory directly from the file system and save an HTTP request.
STATUSCACHEDIRThe directory where all cached endpoint JSONs are kept.
status
    |-- 091_labs.json
    |-- ace_monster_toys.json
    |-- ackspace.json
    |-- backspace.json
    |-- bitlair.json
    |-- cccfr.json
    |-- chaos_darmstadt.json
    |-- chaos_inkl_.json
    |-- ...
Instead of crawling all the JSONs from the endpoints you can use these cached files, which are updated every day. This helps to reduce HTTP requests and thus you minimize execution time and bandwidth. To read a cached endpoint file just use something like
$filename = NiceFileName::get('Laboratorio Hacker de Campinas');
$endpoint = file_get_contents(STATUSCACHEDIR . $filename . '.json');
The class NiceFileName provides the get method which maps the original space name to the file name. The space names themselves can be taken from the directory, where they're the keys for the endpoint URLs.

Classes

Cache

MethodParameterReturn data typeDescription
get($space_name) space name (string) string Returns the cached JSON for the given space name.
get_from_cache($space_name) space name (string) SpaceApiFile Returns a SpaceApiFile object for the cached endpoint.
is_cached($space_name) space name (string) boolean Returns true if there's a cached version available for the passed space.

SpaceApiFile

MethodParameterReturn data typeDescription
__construct($space_name) space name (string) SpaceApiFile Returns a SpaceApiFile object.
email() string Returns the email address from the contact/email field.
version() string Returns the version without the leading zero.
real_version() string Returns the version with the leading zero such as 0.13.

PublicDirectory

MethodParameterReturn data typeDescription
has_space($space_name) space name (string) boolean Returns true if the passed space name is already in the directory.
get_url($space_name) space name (string) string Returns the endpoint URL for the passed space name.
get() json Returns the full directory, as a JSON.
get_stdClass() stdClass Returns the full directory, as a stdClass object.

Worthwhile readings

You might be interested into some security topics.