Was this page helpful?

RESTful API

    Introduction

    RESTfull API is simpler and more suitable delivery of web service for resource oriented Enterprise Applications than SOAP based web service as it provides natural organization of the code and it's API with regard to resource it is related to. Using standard HTTP methods it covers CRUD pattern of access to resource.

    Standards used by Atollon

    Structure of URI

    Each single resource has it's own URI that is used to access the resource. Various operation may be performed upon the resource using various HTTP methods. Also collection of resources have it's own URI. There can also by a structure of the resources and sub-resources.

    Collection resources are accessed using the resource name in the URI scheme as last path element, example of collection of invoices on server atollon:

    https://net.atollon.com/atollon-rest/server/atollon/invoice

    Single resource instance is then accessed thru the resource name and identifier as last path elements, example of invoice resource with identifier 1234000:

    https://net.atollon.com/atollon-rest/server/atollon/invoice/1234000

    Sub-resource identifier can be directly appended to the resource path as last path element if there is only one sub-resource available for given resource, example of invoice's (sub-resource) transaction with identifier 4321000 URI:

    https://net.atollon.com/atollon-rest/server/atollon/invoice/1234000/4321000

    If there can be more sub-resources the you should provide the name of the sub-resource and it's identifier as last path elements:

    https://net.atollon.com/atollon-rest/server/atollon/invoice/1234000/transaction/4321000

    The usual structure of URI looks like this:

    reference to undefined name 'syntax' Exception of type 'MindTouch.Deki.Script.Runtime.DekiScriptUndefinedNameException' was thrown. (click for details)

    where:

    • rest-root-of-server is the root of the server's REST service
    • server-name is name of the server instance containing the resource we want to access
    • root-resource-name is name of the root server's resource i.e. project, invoice, user and so on...
    • root-resource-id is identifier of the root server's resource
    • sub-resource-name is name of the sub-resource of the server's resource
    • sub-resource-id is identifier of the sub-resource of the server's resource

    HTTP Methods

    There is a standard mapping methods to actions performed. The methods and mappings are:

    • GET - retrieve the resource, if the resource URI points to the collection of resources, the collection is retrieved where the URI (query) parameters can be used to filter the collection out
    • POST - if the URI points to the collection of resources it creates new resource in the collection, (optionally) if it points to concrete resource instance then sub-resource may be created if such option is allowed, it usually returns status 201 if resource was successfully created and Location response header contains url of newly created resource
    • PUT - updates the resource the URI points to, (optionally) if URI points to the collection of resources it should replace the collection completely with the new collection provided by the request, ion success (status 200) it returns the updated resource data just like a GET method
    • DELETE - deletes the resource the URI points to, (optionally) if URI is URI of the collection then the whole collection is deleted, the result of this method is usually empty (status 204)
    • HEAD - (optionally) it can be used to query support for the resource - whether the module containing resource exists or the access to resource is applicable in current environment

    User Level Security

    The access to the resources may be restricted to user by use of cookies. The client may use the server resource to log-in. It creates the server resource with the name of the server the user is logged-in and returns a cookie for the URI of the server resource. By the nature of cookies, they are sent with each request to the given server resource or sub-resource of server resource. This allows support for user level security without any additional work on client side except handling of unauthorzied response.

    Cross Origin Security

    Modern browser provide restriction on cross origin resource scripting (CORS). To allow access to the resources from scripts that are not hosted on the same site as the resources itself the server provides support for additional response headers that are sent with the responses. The Access-Control-Allow-Origin header field allows client to accept response if the origin of the scripts that performed that request is listed in the header field value. Additionally Access-Control-Allow-Credentials header field set to true allows client to send credentials in form of cookies with the requests. Additionally to this the server support preflight requests required by CORS in specific cases. The preflight requests are requests send with method OPTIONS and they usually returns empty result or description of the service together with response headers Access-Control-Allow-Methods telling client which methods are allowed by the resource and Access-Control-Allow-Headers that tells client which headers additional to basic headers can be sent.

    The client is only required to use property withCredentials of the XmlHttpRequest to allow browser to send the cookie with the request if necessary and proper Accept header telling server what content type client want the result to be.

    If connecting to resources by other means only Accept and Cookie (if credentials required) header is necessary, the rest depends on concrete resource.

    Responses

    Standard HTTP response codes are used to describe the request outcome. The most often used status codes:

    • 200 OK - the request was successful and returned a response data
    • 201 Created - the POST request was successful, the resource was created and it's URI is returned in Location response header field
    • 204 No Content - request was successful there is no response data returned, used mostly for HEAD or DELETE requests where no response data are expected
    • 400 Bad Request - request failed due to wrong parameters or arguments passed, the result data should contain the cause of the failure (see: badRequest)
    • 401 Unauthorized - accessing a resource that requires user to be authenticated without authentication cookie set
    • 403 Forbidden - accessing a resource that authenticated user has no privilege for, the 404 code may be also used if it is not important to distinguish the non-existing resource from that the user has no privilege for
    • 404 Not Found - accessing not existing resource or resource the user has no privilege for
    • 500 Internal Server Error - this error usually means the problem on server side the client cannot avoid, it identifies either a server bug or miss-configuration

    Content types

    By default all resources should support two content types:

    • application/json - standard JSON data
    • application/xml - standard XML data

    They are supported on both input as payload and output as response data.

    JSON data format

    The JSON result can be either JSON object or null. The following rules applies to JSON data:

    • If collection is supposed to be returned then it is returned as array assigned to property of returned JSON object (usually item).
    • Dates are represented as number of milliseconds since January 1, 1970, 00:00:00 GMT.

    XML data format

    The XML format loosely follow the rules of the standard SOAP messages format:

    • Values are always represented as element contents, attributes are not used.
    • Null values are represented as empty elements with attribute nil="true".
    • Dates are represented in ISO format.

    badRequest

    Bad request (400) response is accopanied by following badRequest entity:

    name value description
    reason string reason why the request is bad
    Was this page helpful?
    Tag page (Edit tags)
    • No tags
    Pages that link here
    Page statistics
    3776 view(s), 11 edit(s), and 9402 character(s)

    Comments

    You must login to post a comment.

    Attach file

    Attachments