G5 API Documentation

gistfile1.md

Contents

• Introduction
• Actions
  • Get Client
  • Get Client Stores
  • Get Client Specials
  • Get Client Unit Categories
  • Get Client Leads
  • Create Special
  • Get Unit
  • Create Unit
  • Update Unit
  • Delete Unit
• Representations
  • Json
• Responses
  • Success
  • Unauthorized
  • Not Found
  • Not Acceptable
  • General Error

Introduction

This is a temporary solution for documentating our public interface to the G5 API. It uses the Git flavored markdown format and should be updated as new Actions are introduced to the API. the majority of it is incomplete - we will need to complete an additional chore/story in an upcoming sprint to close the gaps in the document..

Note: Visit Github's Markdown Preview Page to test out the markdown before pushing to the repository.

Back to Contents

Actions

List of actions supported by the G5 API. The base location for the G5 API is http://api.g5platform.com.

Get Client Leads

Returns leads with specified id.

Request: GET /clients/:client_id/leads

Response Fields:

Field	Description
advertising-end-date	advertising end date
alt-url	alternate url
branded-name	brand name

Back to Contents

Get Client

Returns client with specified id

Returns a client with specified id.

Request: GET /clients/:client_id

Response Fields:

Field	Description
id	ID of Client
branded_name	Name of Client
industry_id	Industry ID

Back to Contents

Get Client Stores

Returns all client's stores.

Request: GET /clients/:client_id/stores

Response Fields:

Field	Description
id	ID of Store
client_site_id	Client's internal id
type	Type of Store: SelfStorageFacility, Apartment Complex, Corporate Office, Senior Care Facility
units	Units for Store

Unit Field	Unit Description
id	Unit's id
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit

Back to Contents

Get Client Specials

Returns all client's specials.

Request: GET /clients/:client_id/specials/

Response Fields:

Field	Description
id	ID of the Special
client_id	ID of the client offering the special
text	Text of the Special

Back to Contents

Get Client Unit Categories

Returns all client unit categories.

Request: GET /clients/:client_id/unit_categories

Response Fields:

Field	Description
id	ID of the Unit Category
name	Descriptive name for display

Back to Contents

Create Special

Creates a new client special.

Request: POST /specials/ Request Fields:

{special:{client_id:1234 ,text:"name",}}

Response Fields:

Field	Description
id	ID of the Special
client_id	ID of the client offering the special
text	Text of the Special

Back to Contents

Get Store Units

Returns all store's units.

Request: GET /stores/:store_id/units

Response Fields:

Field	Description
id	Unit's id
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit

Back to Contents

Get Unit

Returns a unit with specified id.

Request: GET /units/:unit_id

Response Fields:

Field	Description
id	Unit's id
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit

Back to Contents

Create Unit

Creates a new unit.

Request: POST /units

Request:

example:

{unit:{unit_type:"SelfStorageUnit",bedrooms:2,bathrooms:1,special_id:123}}

Resposne Fields:

Field	Description
id	Unit's id
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit
unit_type	Type of Unit: SelfStorageUnit,ApartmentUnit,SeniorCareUnit

Back to Contents

Update Unit

Updates a unit with specified id.

Request: PUT /units/:unit_id

example:

{unit:{id: 123, special_id:123}}

Response Fields:

Field	Description
id	Unit's id
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit
unit_type	Type of Unit: SelfStorageUnit,ApartmentUnit,SeniorCareUnit

Back to Contents

Delete Unit

Deletes a unit with specified id.

Request: DELETE /units/:unit_id

Response Fields:

Field	Description
client_attributes	Client's internal unit id
size	Dimensions of the unit.
rate	Rate for renting the unit.
total_available_units	Number of vacant units.
description	Unit's description
special_id	Unit's current special id
unit_category_id	Unit's current unit category id
unit_ownership_id	Store or Client that manages the unit.
unit_ownership_type	Store or Client
bedrooms	Number of Bedrooms
bathrooms	Number of Bathrooms
floor	Floor number of the unit
sqft	Square footage of the unit
unit_type	Type of Unit: SelfStorageUnit,ApartmentUnit,SeniorCareUnit

Back to Contents

Representations

Json is returned by the API based on the incoming Accept header. If an incoming Accept header is not supported the API will return a Not Acceptable response.

The following is an example of an Accept header for json:

Accept: application/json

Back to Contents

Responses

Every request will return one of the following potential response HTTP status codes:

• Success (200) - Succesful response after a get (GET), update (PUT), or deletion (DELETE) of an object.
• Unauthorized (401) - User is not authorized for the intended request.
• Not Found (404) - Unable to locate requested object.
• Not Acceptable (406) - Accept header is not understood by the API and therefore cannot properly return the properly formatted object.
• General Error (500) - Any application error during the processing of a request. Error message will be return in the requested (Accepts Header) format.

Error Response

Error responses are returned in the body of the HTTP response and provides additional information about the error.

Json Examples:

Industry:

{"id":1,"name":"Self Storage"}	

Client:

{"branded_name":"Self Storage","id":1003,"industry_id":1}

Store:

{"client_site_id":"700903","id":4165,"type":"SelfStorageFacility"}

Unit:

{"bathrooms":null,"bedrooms":null,"client_attributes":"100598","description":"Climate controlled storage, Upstairs access via elevator","floor":null,"id":58939,"rate":"389.0","size":"26X20","special_id":null,"sqft":null,"total_available_units":0,"unit_category_id":354,"unit_ownership_id":115,"unit_ownership_type":"Store","encoded_description":"CEN","occupancy_rate":"100.0","reservation_days":"30","hide_on_reservations_page":"0","reservation_rate":"10"}

Special

{"client_id":1003,"id":1611,"text":"Two Months Half Off Lowest Price Guarantee"}

Unit Category

{"id":354,"name":"10' X 30' (Up to 300 sq ft)"}

Lead

{"address"=>nil, "address2"=>nil, "city"=>nil, "client_id"=>1003, "created_at"=>2011-01-02 06:18:11 UTC, "email"=>"osulsea@chrobinson.com", "first_name"=>"Sean", "id"=>303969, "last_name"=>"O'Sullivan", "lead_reference_id"=>1619, "lead_reference_type"=>"Store", "message"=>"Looking for quote or specials related to this size or similar? I have had other companies offer the use of a free van?", "state"=>nil, "telephone"=>"773-320-4584", "unique_code"=>"dc42c-72254", "zip"=>nil, "start_date"=>#<Date: 2011-01-02 (4911127/2,0,2299161)>, "units"=>"05X15", "inbound_referer_page"=>"http://www.unitedstorall.com/self_storage/Chicago_IL/zip_60647/united_stor-all/1619"}

Back to Contents