Home Page / Documentation / Astroboa APIs / Resource API (RESTful)

Resource API (RESTful)

Astroboa Resource API is motivated by the following key concept:

"Your Data is Your Web Server"

From the perspective of web / mobile application developers, the Resource API is a RESTful interface to the information modeled and stored in Astroboa repositories. An easy and fast way to integrate Astroboa as a web service in Web 2.0 applications.

The Resource API exposes your data as information resources which can be easily and directly accessed in the web through simple URIs. It allows searching, retrieving and creating structured data by means of URI requests. In other words, it transforms your  data repository into the web server itself without the need for intermediate layers.

Every object or object collection stored in the repository is a resource that can be "RESTfully" accesed by any application and any programming language. No need to write additional code for your data API layer. The repository facilitates an architecture that securily exposes every object or object collection though a URL. The objects properties themselves are URI addressable (every object property has a URL) resulting in a true "hypertext driven" REST API that provides "Domain Data Declarative Hyperlinking". In simpler words, you can navigate the information in the repository (the object tree and the properties in each object) as easy as you navigate web pages. In the web you are not required to know any special language to get the information that you want. As soon as you know the home page URL you are done. Each page is responsible to give you the LINKS to the connected pages. This is true for a Astroboa repository, extended to any object type (aka Entity) besides the traditional web pages. You do not need to know special verbs (i.e. RMI Calls) to access your objects. As soon as you know the URL for a repository you can GET / PUT / POST / DELETE objects and navigate to other objects using the LINKS (URLs) that each object provides.

Astroboa resource API produces XML and JSON output that is structured according to information model you have defined. It can also export any object or object collection in MS EXCEL and CSV. Other resource representation formats like RDF, HTML and ATOM will be supported in future releases of Astroboa.

Before we go through the details of the Astroboa RESTful API, we describe the base URI which is common to all RESTful API requests.

Base URI path of API calls

All RESTful API calls share a common base URI which adheres to the following pattern:

	http://<Astroboa-host-or-IP>/resource-api/<repository-id>

where <Astroboa-host-or-IP> is the hostname or the IP address of the server that hosts repositories and <repository-id> denotes the name of the repository to which API requests are addressed to.

Thus, the URI pattern below can be translated as follows:

	http://some-server/resource-api/musicstore

Access resources that reside in an Astroboa repository named 'musicstore' located in 'some-server'.

The basic URI part is suffixed with information about the type of resource to be accessed (e.g. content object, taxonomy, topic) along with the necessary parameters that further identify the exact resource properties.

Astroboa Entities offered through RESTful API

Don't forget to have a look on the Entity identifiers used in Astroboa.

API Security

The Astroboa Resource API provides both public (unauthenticated) and private (authenticated) access to the content of a repository through HTTP Basic Authentication. Thus, the same repository can deliver different content based on the way it is accessed. A public-unauthenticated request for content, allows access only to published content of a repository. On the other hand, no such restriction applies to private-authenticated requests. The content of a repository refers to the Content Objects of it, and not to Taxonomies and Topics. Therefore, both unauthenticated and authenticated requests for Taxonomies and Topics will deliver the same results. An unauthenticated request will retrieve at most 50 Content Objects to prevent repository abuse. However, it is possible to access all published Content Objects when issuing paginated requests, that is requests with special query parameters (offset & limit). Responses of authenticated requests are not subject to any size limits. Authenticated requests are supported through HTTP Basic Authentication providing username and password credentials. Future releases will also consider OAuth.

In order to access public content in a repository, run:

	curl http://myAstroboaHost/resource-api/myRepositoryId/...

In order to access private content of a repository, providing username and password credentials, run:

	curl -u username:password http://myAstroboaHost/resource-api/myRepositoryId/...

curl will encode (base64) username and password.

Here is how to perform an authenticated request using JQuery:

var requestData = '...';
var username = 'username';
var password = 'password';

/*
 * You have to load jQuery base64 plugin (jquery.base64.js)
 * to use $.base64Encode function.
 *
 * Empty space is required after 'Basic'.
 * ':' is used between  username and password
 */
var authorizationHeader = 'Basic ' + $.base64Encode(username + ":" + password);

$.ajax('http://<Base URI path>/<entity-path>', {
 type: 'GET, PUT, POST, DELETE',
 data: requestData,
 beforeSend: function(req) {
  req.setRequestHeader("Authorization", authorizationHeader);
 },
 success: function(data, textStatus, response) {
  // Action on Success
 },
 error: function(res, textStatus) {
  // Action or Error
 }
});

Authenticated Resource API requests assume that you already have a user account in the repository you are trying to access. You may create a user account by creating an instance-object of the personType type. The personType provides the personAuthentication property which holds user's credentials i.e. username and password.  

Moreover every contentType that extends the personType automatically inherits the personAuthentication property. Therefore, every instance of a content type that extends the personType represents a possible user account in the Astroboa repository. We say possible because if no credentials are provided then it will not be possible to successfuly authenticate in the Astroboa repository. Every Astroboa valid user may create instances of any content type.