REST APIs

Startup API package provides it's core APIs through HTTP RESTful web services at /api.php URL.

Applications using Startup API can also expose it's functionality through a centralized API handler.

All endpoints registered with application instance are listed at /api.php URL, interactive API console is a feature for future development.

Making calls

To make API calls, you need to provide a required endpoint slug as call parameter, for example:

GET http://www.myapp.com/users/api.php?call=/startupapi/v1/user

which will provide information for a currently logged in user.

Passing parameters

Each endpoint might accept additional parameters which are listed below the endpoint. For GET endpoints, you can just add URL-encoded parameters to a query string:

GET http://www.myapp.com/users/api.php?call=/startupapi/v1/user&id=1

For methods that support request body (e.g. POST or PUT), you can send them in as a form-url-encoded values.

Parameters can be optional or required and some can also support multiple values, you can send multiple values for the same parameter, but just using it multiple times in the URL like:

GET http://www.myapp.com/users/api.php?call=/startupapi/v1/user&id=1&id=2&id=3

Raw request bodies

Some endpoints might also accept content as raw request body, each endpoint is responsible for parsing and understanding the content of that body, if necessary.

Responses

Response of the call is a JSON object with meta value containing information about the request and result value containing the result of the API call.

{
    "meta": {
        "call": "/startupapi/v1/user",
        "success": true,
        "params": []
    },
    "result": {
        "id": 1,
        "name": "Sergey Chernyshev"
    }
}

Errors

If API call is successful, meta.success property will be set to true and result will contain result of the call.

Otherwise, meta.success will be set to false and meta.error will contain error message, with optional error code in meta.field. In case of an error result will not be set.

HTTP response code will also be set to a corresponding error code.

{
    "meta": {
        "call": "\/startupapi\/v1\/user",
        "success": false,
        "error": "[StartupAPI] No such user",
    }
}

CSRF protection

Basic CSRF protection is supported by checking for a custom X-CSRF-token request header with any value - this should be enough to ensure that the call is issued from the same origin.

---

Implementing your own endpoints

Your application can expose it's own APIs through the same mechanism and benefit from all the authentication methods and handling infrastructure that is already built for Startup API's own infrastructure.

Implementing Endpoints

In order to implement your own endpoint you need to subclass \StartupAPI\API\Endpoint class or one of it's subclasses, e.g. \StartupAPI\API\AuthenticatedEndpoint.

Implement constructor

Call Parent's Constructor

In your implementation call parent's constructor and specify following parameters:

• $slug - URL-friendly unique identifier (slug) that should start with the slash can contain slashes, dashes, latin letters and numbers, e.g. /v1/student
• $description - description of the endpoint to be displayed on documentation page

Set Endpoint Parameters

If your method supports parameters, you should register them in constructor by setting $this->param to an associative array of name-value pairs:

public function __construct() {
	parent::__construct('/v1/student', 'Create new student under specified account');

	$this->params = array(
		'account_id' => new \StartupAPI\API\Parameter("Account ID", 1),
		'name' => new \StartupAPI\API\Parameter("Student Name", "John Smith")
	});

Override call() method

Implementing the endpoint is as simple as overriding call() PHP method.

First line should be calling parent's call() method

public function call($values, $raw_request_body = null) {
	parent::call($values);
	...
}

Getting User Object

If you subclassed \StartupAPI\API\AuthenticatedEndpoint then you can easily get currently authenticated user by capturing the value returned from parent's call() method.

public function call($values, $raw_request_body = null) {
	$user = parent::call($values);

	$name = $user->getName();
	...
}

Return value

Return value for the call is a simple nested associative array with any level of nesting.

It will be combined with some request-related metadata and returned as a value to result key in JSON payload.

ObjectNotFoundException

You can throw ObjectNotFoundException> to indicate that object requested was not found in the system (will return 404)

Sample Implementation

namespace MyApp\API\Student;
class Create extends \StartupAPI\API\AuthenticatedEndpoint {

	public function __construct() {
		parent::__construct('/v1/student', 'Create new student under specified account');

		$this->params = array(
			'account_id' => new \StartupAPI\API\Parameter("Account ID", 1),
			'name' => new \StartupAPI\API\Parameter("Student Name", "John Smith")
		});
	}

	public function call($values, $raw_request_body = null) {
		$user = parent::call($values);

		return array(
			'id' => 42,
			'name' => 'Malcolm'
		);
	}

}

Register Your Endpoint

After you implemented an endpoint class, you need to register and instance of it with Startup API in your users_config.php file.

Create API Namespace

In order to register an endpoint, you first need to create an API Namespace object representing all of your calls:

require_once(__DIR__ . '/users/classes/API/EndpointNameSpace.php');
$my_api_namespace = new \StartupAPI\API\EndpointNameSpace('myapp', 'My app API', 'API endpoints for my application');

Register Endpoint Instance

require_once(__DIR__ . '/users/classes/API/Endpoint.php');
require_once(__DIR__ . '/classes/API/Student/Create.php');
\StartupAPI\API\Endpoint::register($my_api_namespace, 'GET', new \MyApp\API\Student\Create());