EnergyCAP Online JSON REST-based API

EnergyCAP OnlineJSON REST-based APIPresented by Ryan Booz, BEP

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

What is an API?

Application Programming Interface

A defined way of using an application’s functionality outside of the application itself

The predominant method of getting data with mobile applications

Not a standard, but is composed of standards

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Popular Examples: Google Maps

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Popular Examples: Twitter

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Popular Examples: Facebook

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Popular Examples: Netflix

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Popular Examples: Pinterest

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

RESTRepresentational State Transfer

Use native HTTP protocol/statuses as the method for communicating

Focus is on the specific objects rather than specific functions

Objects accessed directly by URI

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

EnergyCAP API Goals

Develop an API that we would enjoy using (because we will)

Assume (almost) all future EnergyCAP development will utilize the API

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

EnergyCAP API GoalsInclude enough META information to be helpful while still staying REST-ful

When it makes sense, REST is not god. We can provide more coupled services on rare occurrences

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

EnergyCAP API Goals

Most GET APIs will allow:Querying

Filtering

Documentation will be a requirement of the development process

Documented APIs are supported, undocumented APIs are not

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

EnergyCAP API V2

In most cases, V2 is our first, 100% supported API version

Limited V1 APIs will be supported as we move everything to V2

V2 brings consistency in requests and responses, permissions and technology

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Example: BuildingsREST: (the new way)

http://server/api/v2/place

VERB=GET

Headers control content-type

Any browser or development tool can use REST services without additional plugins

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Example: Place

{ “Data": [ { "placeID": 1, "placeCode": “RADNOROFFICE", "placeInfo": “Radnor Office", "parentID": 4, "createdBy": 5, "createdDate": "2014-04-28T12:31:41.7184412-04:00", "modifiedBy": 7, "modifiedDate": "2014-04-28T12:31:41.7194622-04:00", "placeTypeID": 9, "PlaceType": {

"placeTypeID": 3,"placeTypeCode": “OFFICE","placeTypeInfo": “Office Building“

} ]}

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Example: Place

All Places: (GET)

http://server/api/v2/place

Specific Places: (GET)

http://server/api/v2/place/1234

Create Places: (POST)

http://server/api/v2/place

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Example: Place

Update Place: (PUT)

http://server/api/v2/place/1234

Delete Place: (DELETE)

http://server/api/v2/place/1234

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Public vs. Private API

The EnergyCAP Public API will be a subset of our internal, private API

You will NOT be able to do everything through the API

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Public vs. Private API

Public API will be documented and available through common URL

When you have EnergyCAP 3.2 or greater, you have access to the SUPPORTED API

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Public vs. Private API

Once someone incorporates an API into their business process, we must provide support until it is properly deprecated

Data “objects” and some processors are the first priority

Data-centric, not UI

You cannot request a chart image through the API

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Access

http://server/api/docs

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Demo

©2014 EnergyCAP, Inc. ▪ @energycap ▪ www.EnergyCAP.com

Questions

Visit the Ace Place to learn more!