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).
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.
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
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
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.
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>
This method specifies the version using a query path parameter, for example:
http://server:port/myapp/cars/1?version=1
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.
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 |
Status Code | Message | Description |
401 | Unauthorized | The request requires user authentication |
404 | Not Found | The resource requested does not exist |
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 |
Status Code | Message | Body |
200 | OK | The update data |
Headers:
Header | Description |
Location | URL to the resource |
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. |
http://server:port/myapp/v1/cars/1
Status Code | Message | Body |
201 | Created | The newly added data |
Header | Description |
Location | URL to the newly created resource |
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. |
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 |
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.
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. |
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. |
Status Code | Message | Body |
200 | OK | The credentials in JSON format. __TODO__ Provide an example here. |
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. |
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 |