Introduction

The storEDGE API is a REST API. It uses one-legged OAuth 1.0 as its authentication mechanism.

Documentation Links

• API V1 Docs
• Swagger UI
• Swagger JSON Schema

URLs

All communication is done over HTTPS, there is no non-secure access. All storEDGE URL’s adhere to the following format:

https:///:version_identifier/:facility_id/:resource((/:resource_id)((/:subresource)(/:subresource_id)))

A URL in practice would be something like:

https:///v1/843eee43­55b7­4b25­85c4­c555ba7f43fa/ledgers/2c7b16bb­-a760­-4938­-b942­44f719e-05529

In other words, all storEDGE API calls have an API version and facility context based on the base URL.

Implementation

Recommended Libraries

• Ruby:
  • Plain Ruby: http://rubygems.org/gems/oauth
  • Rails: http://rubygems.org/gems/oauth-plugin
• .NET:
  • RestSharp: https://github.com/restsharp/RestSharp
• PHP:
  • Composer: https://getcomposer.org/
  • Guzzle: http://docs.guzzlephp.org/en/stable/overview.html#installation
  • Guzzle OAuth Subscriber: https://github.com/guzzle/oauth-subscriber
• Java:
  • Signpost: https://github.com/mttkay/signpost
  • Gson: https://github.com/google/gson

Sample Implementations

• .NET: https://github.com/rednovalabs/storedge-api-client-dotnet
• PHP: https://github.com/rednovalabs/storedge-api-client-php
• Java: https://github.com/rednovalabs/storedge-api-client-java

Identification and Authentication

The storEDGE API uses OAuth 1.0 as its authentication mechanism. Whereas in many OAuth implementations you would have three steps (application<->service, service<->user, service<->application), storEDGE uses only one leg (application<->service), hence the term "one-legged". For a description of the various OAuth 1.0 flows, please see https://github.com/Mashape/mashape-oauth/blob/master/FLOWS.md

You will need three pieces of information to communicate with the API:

• API access ID This ID is attached to a particular company and is created by your users and provided to you by them. Put this in your OAuth config as the consumer key.
• API secret key Also provided by your users. Put this in your OAuth config as the consumer secret.
• Facility ID Your users will provide this to you as well. Put this directly into the URL.

Example time!

Let's say you are building a new website to help people improve their tailgating parties when they attend sports games. You will provide the latest tailgating news, the ability to purchase tailgating supplies, and an extensive library of in-depth articles. As part of your site, tailgaters can find storage units based on proximity to stadiums so that they can easily store their tailgating supplies. In fact, they can even arrange to have items purchased through your site delivered directly to the storage facility. Facility owners can pay you to be listed on your website, "TailgatingTactics.net", and of course you would like to have up-to-date unit pricing and availability.

Mr. Sluggerrr has a facility, "Sluggerrr's Storage", located just down the street from Kauffman Stadium. Storage has been slow of late so he decides that being listed on TailgatingTactics.net would be just the thing. Conveniently, he is using storEDGE as his management software. He sets up a user on storEDGE and provides you the following information:

• Access ID: MNO
• Access Secret: PQR
• Facility ID: 36HJ

When TailgatingTactics.net performs a request to retrieve the units list at Sluggerrr's Storage, the request will include the following information:

• Access ID: MNO
• Access Secret: PQR
• Facility ID: 36HJ

Mrs. Wolf has two facilities, "Wolf's Storage" and "Wolf's Storage II", located just down the street from Arrowhead Stadium. Since these two stadiums are adjacent, Mrs. Wolf and Mr. Sluggerrr are intense competitors. When she notices Sluggerrr's Storage listed on TailgatingTactics.net, she decides that she must list both of her facilities as well. She sets up a user on storEDGE and provides you the following information:

• Access ID: MNO
• Access Secret: PQR
• Facility ID for Wolf's Storage: 78DN
• Facility ID for Wolf's Storage II: 69EJ

When TailgatingTactics.net performs a request to retrieve the units list at Wolf's Storage, the request will include the following information:

• Access ID: MNO
• Access Secret: PQR
• Facility ID: 78DN

And for Wolf's Storage II:

• Access ID: MNO
• Access Secret: PQR
• Facility ID: 69EJ

Notice that in all three examples, the access ID is the same because it corresponds to your application, TailgatingTactics.net. The facility ID is obviously specific to each facility. In the case of Mrs. Wolf, the access ID and secret are the same for both facilities because they are under the same company.

Formats and Headers

The storEDGE API sends and receives data in JSON format. For more info on JSON, check out http://json.org.

It is highly recommended that the standard Content­-Type and Accept headers be included on every storEDGE API call. Since the format is JSON, the values of these headers should be application/json. Some calls may not succeed without these headers.

Responses

Standard HTTP response codes are used as strictly as possible to indicate the status of a request. You can find a list of codes at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

All response bodies return a meta hash which indicates the parameters received, the request method, pagination details (if applicable), status code and message, etc. For example:

{
  "meta": {
    "message": "Invalid OAuth Request",
    "status_code": 401,
    "request_id": "ccfe50a7-268a-49e0-bc9b-1265d440bffe",
    "error_code": 2,
    "status_message": "Bad Request",
    "status_cat": "http://httpcats.herokuapp.com/400",
    "parameters": {
      "path": "/"
    },
    "request_method": "GET"
  }
}

If the response is an error, the meta hash will include several useful keys:

• error_code indicating the particular error that has occurred so that you may check the response for specific errors if you need to.
• request_id giving a unique ID to this request. This may be useful in corresponding with storEDGE regarding a particular request or error that you are having trouble with.

Error Codes

The possible error codes are:

• Code 1 - Api Error
  HTTP status: Internal Server Error (500)
  Description: Unknown API error. Sorry.

• Code 2 - Authentication Failed
  HTTP status: Unauthorized (401)
  Description: Invalid OAuth Request

• Code 3 - Action Failed
  HTTP status: Bad Request (400)
  Description: The requested action could not be performed.

• Code 4 - Missing Or Invalid Parameter
  HTTP status: Bad Request (400)
  Description: At least one parameter was missing or did not match validation criteria.

• Code 5 - Conflicting Parameters
  HTTP status: Bad Request (400)
  Description: The supplied parameters conflict with one another.

• Code 6 - Cannot Change Reservation
  HTTP status: Bad Request (400)
  Description: Reservations cannot be unreserved. Please close this lead and create a new one or contact the facility.

• Code 7 - Tenant Access Denied
  HTTP status: Bad Request (400)
  Description: The requested action has been disabled for tenants. Please visit the facility for more information.

• Code 8 - Invalid Login Or Password
  HTTP status: Bad Request (400)
  Description: The login and/or password provided was incorrect.

• Code 9 - Resource Not Found
  HTTP status: Not Found (404)
  Description: The resource you requested could not be found.

• Code 10 - Invalid Sort Parameter
  HTTP status: Bad Request (400)
  Description: Either the sort parameter you specified is not supported, or this resource does not support sorting.

• Code 11 - Tenant Already Signed Up
  HTTP status: Bad Request (400)
  Description: The tenant account you are trying to register already has an account setup.

• Code 12 - Refund Already Voided
  HTTP status: Bad Request (400)
  Description: The refund requested has already been voided

• Code 13 - Unauthorized Access
  HTTP status: Forbidden (403)
  Description: The client does not have access rights to the requested content.

Response Code Suppression

Some client technologies do not gracefully handle HTTP status codes that are not 200 (OK) or 500 (Internal server error). While not recommended, you can force the HTTP status code to always be 200 (OK). The meta data that is returned on every response body will still contain the true status code in the status_code field. To use this option on a call without a request body, you can pass in the suppress_response_codes=true query parameter on the URL. On a call with a request body (such as a POST), you can add this parameter directly into the body, like so:

{
  "suppress_response_codes": true,
  "lead": {
    "is_reservation": false,
    ...
  }
}

Pagination

Any call that returns a collection can be limited using the per_page and page query parameters. For example:

https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?per_page=25&page=2

Any request that supports pagination will include information about it in the response. By default responses are limited to 100 items.

  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "per_page": 100,
      "total_entries": 4,
      "previous_page": null,
      "next_page": null
    },
    "status_code": 200,
    "status_message": "OK",
    "status_cat": "http://httpcats.herokuapp.com/200",
    "parameters": {
      "facility_id": "622c5ea6-a85a-4579-8e5f-484d8c97eccc"
    },
    "request_method": "GET"
  }

Sorting

Some calls that return a collection can be sorted using the sort query parameter. Multiple sorting criteria can be specified with a comma. The sort order can be changed by prepending the sort parameter with either a + or -.
A valid list of sort options can be found on the page for each resource.

Sparse Fields

In some cases the response returned from the API is gigantic and contains a lot of data you don't care about. In these cases, it is useful to specify which fields will be returned for a given type of object. This roughly mirrors the JSON API spec at http://jsonapi.org/format/#fetching-sparse-fieldsets.

When you specify which fields are to be returned, only those fields are returned. This applies to associations and nested objects as well.

Generally the name of the object is the singularized name of the class.

Let's say you are loading ledgers, which happens to include information about the ledger and also embeds the unit. Perhaps you'd only like to see a few of these data points:

https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/ledgers?fields[ledger]=current_rate,unit,id&fields[unit]=name,size,price

Creation Time Filtering

Any call that returns a collection can be limited using the created_after and/or created_before query parameters, which will cause only results created between given timestamps to be returned. You may supply one or both of these parameters. The parameter format is parsed using a series of heuristics so any reasonably-formatted timestamp should work, however, it is suggested that you use ISO 8601/RFC 3339 (http://www.ietf.org/rfc/rfc3339.txt). Many programming languages already have the ability to convert to this format.

https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?created_after=2014-07-15T10:37:25-05:00
https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?created_before=2014-07-15T10:37:25-05:00
https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?created_after=2014-07-15T10:37:25-05:00&created_before=2014-07-16T10:37:25-05:00

Updated Since Filtering

Any call that returns a collection can be limited using the updated_since query parameter, which will cause only results changed since the given timestamp to be returned. The parameter format is parsed using a series of heuristics so any reasonably-formatted timestamp should work, however, it is suggested that you use ISO 8601/RFC 3339 (http://www.ietf.org/rfc/rfc3339.txt). Many programming languages already have the ability to convert to this format.

https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?updated_since=2014-07-15T10:37:25-05:00

ID Filtering

Any call that returns a collection can be limited using the only_ids query parameter, which will cause only the specified records to be returned. The parameter should be a comma-separated list of IDs. This is useful if you already know the IDs of the records you want.

https:///v1/c9ed5cc6­eeb9­4f85­94d2­3fc8c5162887/tenants?only_ids=622c5ea6-a85a-4579-8e5f-484d8c97eccc,ccfe50a7-268a-49e0-bc9b-1265d440bffe

Sideloading

The storEDGE API inherently returns robust JSON structures. This is intended to make the consumer’s job easier, so that most (if not all) of the information you need is returned from the original call, rather than having to make a series of subsequent calls with associated ID’s.

For example, the GET /units call will return the amenities and unit type for each unit in the facility:

{
  "units": [
    {
      "id": "d41d99ec­913b­41f3­8756­4717f0ef265f",
      ...
      "unit_amenities": [
        {
          "id": "ffadbe8c­cee8­41fb­a453­4563f239cda0",
          "name": "Heated"
        },
        {
          "id": "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d",
          "name": "Stacked Space"
        },
      ],
      "unit_type": {
        "id": "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f",
        "name": "Parking Space"
      }
    },
    {
      "id": "244388ea­a18a­4dc5­bbee­61f02f4521a1",
      ...
      "unit_amenities": [
        {
          "id": "ffadbe8c­cee8­41fb­a453­4563f239cda0",
          "name": "Heated"
        },
        {
          "id": "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d",
          "name": "Stacked Space"
        },
      ],
      "unit_type": {
        "id": "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f",
        "name": "Parking Space"
      }
    }
  ]
}

While this is convenient if the consumer’s intention is to retrieve one or two units, this data becomes quite redundant if applied to tens or hundreds of units. The overhead of this data may no longer be worth the cost of the convenience. Sideloading is a tool consumers can use to address this issue.

On a GET call, passing the sideload=true query parameter on the URL will restructure the data so that the common elements are extracted from each struct’s body and listed in a separate, named section of the response. Applying this strategy to the example above yields the following:

{
  "unit_amenities": {
    "ffadbe8c­cee8­41fb­a453­4563f239cda0": {
      "id": "ffadbe8c­cee8­41fb­a453­4563f239cda0",
      "name": "Heated"
    },
    "90ebf9fe­19fc­48df­a71d­f9a47aba291e": {
      "id": "90ebf9fe­19fc­48df­a71d­f9a47aba291e",
      "name": "Air Cooled"
    },
    "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d": {
      "id": "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d",
      "name": "Stacked Space"
    }
    ...
  },
  "unit_types": {
    ...
    "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f": {
      "id": "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f",
      "name": "Parking Space"
    }
  },
  "units": [
    {
      "id": "d41d99ec­913b­41f3­8756­4717f0ef265f",
      ...
      "unit_amenity_ids": [
        "ffadbe8c­cee8­41fb­a453­4563f239cda0",
        "90ebf9fe­19fc­48df­a71d­f9a47aba291e",
        "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d"
      ],
      "unit_type_id": "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f"
    },
    {
      "id": "244388ea­a18a­4dc5­bbee­61f02f4521a1",
      ...
      "unit_amenity_ids": [
        "ffadbe8c­cee8­41fb­a453­4563f239cda0",
        "90ebf9fe­19fc­48df­a71d­f9a47aba291e",
        "fd41eeb0­aae8­40f4­a6c0­e97bc8544e8d"
      ],
      "unit_type_id": "fc8828e4­ae1d­41f5­84bb­28d27d4c7a2f"
    }
  ]
}

On a call with a request body (such as a POST), you can add this parameter directly into the body, like so:

{
  "sideload": true,
  "lead": {
    "is_reservation": false,
    ...
  }
}

Including Objects or Just IDs

Depending on what you're doing with the API, sometimes you might want more or less associated data returned with the response. For example, when fetching tenants, you might simply want a list of the current ledger IDs for tenants. Or you instead may wish to receive the ledger object included in the request directly. We have tried to choose sensible defaults for every association, but you can choose to override them.

Including Objects

You can pass the include_as_object parameter with a list of associations to include the entire object. The list should be comma-separated, like so include_as_object=facility,phone_numbers,mailing_address. Note that this option has no effect when sideload=true is specified, because by definition sideloading includes the associated object ID in the record.

Including Just IDs

You can pass the include_as_id parameter with a list of associations to include just the ID. The list should be comma-separated, like so include_as_id=facility,phone_numbers,mailing_address.