Introduction

This document provide practical examples on how to use the DDO Locations API to manage locations.

This is a RESTful API which forms a different paradigm to the RPC-style we can see, for example in SOAP APIs.

The main premise is that we're not invoking functions but interacting with resources and we use the HTTP protocol's operations / verbs and standard HTTP Status codes to signal success or failure.

HTTP Request Methods

The resource in our case is locations with which we interact by using the appropriate HTTP request methods:

  • POST create a location or opening times rules
      /locations
    
  • GET retrieve the list of available locations or a specific one or the opening times rules for a specific location
      /locations/<id>
      /locations/<id>/openingTimesRules
    
  • DELETE remove a location
       /locations/<id>
    
  • PUT update location or opening times rules (use case: change the store name or disable a location for a given day)
      /locations/<id>
    

HTTP Status Codes

Another guideline for RESTful APIs which we follow is in using the appropriate HTTP Status Code to provide a status about the operation which the user has attempted. Additional information is frequently included as part of the response body but the overall status (created, server error, partial content, ...) can be obtained directly.

We are currently using the following codes listed below.

Location or opening times rules created:

HTTP/1.1 201 CREATED

Retrieved, deleted or updated a location or opening times rules, successfully:

HTTP/1.1 200 OK

Request error; e.g. invalid JSON object or invalid UUID string:

HTTP/1.1 400 BAD REQUEST

Entity with provided id does not exist:

HTTP/1.1 404 NOT FOUND

Other errors:

HTTP/1.1 500 INTERNAL SERVER ERROR

HATEOAS

HATEOAS stands for: Hypermedia As The Engine Of Application State. We incorporate this concept in our API by providing links to resources in the response for some operations. As an example, when creating a new Location, you should get a JSON object in the response body which contains the link for the Location which was just created.

Example:

{
  "rel": "self",
  "href": "/locations/e7f936c"
}

We can then retrieve the opening times rules for this location by performing a GET request on /locations/e7f936c

Authentication and Authorization

All of the requests described in this document must contain a valid OAuth 2 bearer token (see Authentication and Authorization).

results matching ""

    No results matching ""