AeroGear Server Side Interfaces

gistfile1.md

AeroGear Server Side Interfaces

This document describes the server side interfaces for AeroGear. Since all interactions use the Http protocol the interfaces in question are resource URLs.

Some of the exposed resource URLs are specific to AeroGear, for example if AeroGear-Security is in use, then there are certain URL that are exposed by default. But for most of the resource URLs the actual composition of the URLs is specific to the server side application. This document's indent is to be a guide for users creating new RESTful server side applications as well as for client developers to know how to interact with RESTful applications (what request/responses will look like).

Transport protocol

The APIs described in this document are based on Hypertext Transfer Protocol, version 1.1 and https is recommended. Please refer to the security section of this document for details why https is important.

Resources

A resource, or an endpoint, is identified by an URL which is referred to as the resource url. For example, if you might have a resource of cars:

http://server:port/myapp/cars

When requesting data from a resource you often want to specify the format of the returned data. This is accomplished by using a Http header named "Accept":

Accept: application/json

BaseURL

All AeroGear client libraries (JavaScript, Objective-C, and Android) have the concept of a base url when creating a pipeline. This base url is the path to your application running somewhere. For example, say you deploy a web application with a context path of myapp to web/application server. The base url is the would be the URL to the root of this web application,

http://server:port/myapp

Versioning

Depending on the application in question you might want to version it. There are several approaches to versioning RESTful application and we will discuss the methods in this section.

Using separate URLs

This method separates two version of application by using different URLs to the resource. In this case you might have version 1 deployed with a context path of:

http://server:port/myapp/v1

And later deploy version 2 as:

http://server:port/myapp/v2

Configuring the context path is specific to your web/application server. For example, configuring a context path for AS7 you would add a WEB-INF/jboss-web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <context-root>myapp/v1</context-root>
</jboss-web>

Using a Query parameter

This method specifies the version using a query path parameter, for example:

http://server:port/myapp/cars/1?version=1

Using the Mediatype

This method uses the HTTP Accept and Content-Type headers to handle versioning of data as well as describing data. A client uses the Http request header "Accept" to specify the media type(s) that it accepts. Using this method one can specify both the type wanted and the version:

Accept: application/vnd.myapp.cars+json; version=1.0

Note that you can create your own MIME types using the vnd (vendor) prefix, which is what the example above is doing. When a client requests data from your service, they create an HTTP request and set the Accept header to the correct MIME type.

HTTP Methods

GET

Example of reading a resource, in this case a car with a certain id:

http://server:port/myapp/v1/cars/1

If the above resource exists the following response should be returned:

Status Code	Message	Body
200	OK	Resource in requested format

Possible Error Responses:

Status Code	Message	Description
401	Unauthorized	The request requires user authentication
404	Not Found	The resource requested does not exist

PUT

http://server:port/myapp/v1/cars/1

If the the resource does not exist the following response should be returned:

Status Code	Message	Body
201	Created	The newly added data

And if the resource already exists, this will be considered an update and the response will be:

Status Code	Message	Body
200	OK	The update data

A reason for returning the data could be that the server needs to process the data, for example, it might need to generate an unique id or something like that.

Headers:

Header	Description
Location	URL to the resource

Possible Error Responses:

Status Code	Message	Description
400	Bad Request	The format of the clients request was incorrect.
401	Unauthorized	The request requires user authentication
409	Conflict	The data passed in conflicted with the stored data and an update was not possible
415	Unsupported Media Type	The requested media type is not supported by the server.

POST

http://server:port/myapp/v1/cars/1

Status Code	Message	Body
201	Created	The newly added data

Headers:

Header	Description
Location	URL to the newly created resource

Possible Error Responses:

Status Code	Message	Description
400	Bad Request	The format of the clients request was incorrect.
401	Unauthorized	The request requires user authentication
409	Conflict	The data passed in conflicted with the stored data and an update was not possible
415	Unsupported Media Type	The requested media type is not supported by the server.

Delete

http://server:port/myapp/v1/cars/1

Status Code	Message	Body
203	No Content	N/A

Possible Error Responses:

Status Code	Message	Description
401	Unauthorized	The request requires user authentication
404	Not Found	The resource requested does not exist

AeroGear-Security

When AeroGear-Security is used as the SecurityProvider for AeroGear-Controller, or possibly deployed standalone, it has a number of endpoints that it exposes which handle different authentication aspects.

Registering a user

http://server:host/myapp/auth/register

Response code upon successful registration:

Status Code	Message	Body
200	OK	The credentials in JSON format. __TODO__ Provide an example here.

Headers:

Header	Description
Auth-Token	The authentication token for the registered and now logged-in user

Possible Error Responses:

Status Code	Message	Description
400	Bad Request	The request could not be understood by the server due to malformed syntax.

### Login ### ```html http://server:host/myapp/auth/login ``` Response code upon successful login:

Status Code	Message	Body
200	OK	The credentials in JSON format. __TODO__ Provide an example here.

Headers:

Header	Description
Auth-Token	The authentication token for the registered and now logged-in user

Possible Error Responses:

Status Code	Message	Description
400	Bad Request	The request could not be understood by the server due to malformed syntax.

Logout

http://server:host/myapp/auth/logout

Response code upon successful logout:

Status Code	Message	Body
200	OK	N/A

Possible Error Responses:

Status Code	Message	Description
400	Bad Request	The request could not be understood by the server due to malformed syntax.
401	Unauthorized	The request requires user authentication