API Overview

From ampEducator

Contents 1 Introduction 1.1 POST 1.2 GET 1.3 PUT 1.4 DELETE 2 Setup & Authentication 3 Endpoint URL 4 Parameters 5 Dates & Times 6 Encoding

Introduction

ampEducator offers an easy to use and powerful RESTFul API gateway allowing you to move information in and out of the application effortlessly. The API gateway is accessed by posting HTTP request queries and receiving data in XML or JSON formats. There are four basic operations: POST, GET, PUT and DELETE.

POST

To add a new prospect to ABC School we can do the following:

https://username:password@abcschool.ampeducator.com/api/v1/prospects?method=POST&firstName=John&lastName=Smith&responseType=xml

In response we would get something like:

<response statusCode="200" statusMessage="OK" method="POST">

  <metaData/>
  <messages> 
    <general>The prospect was successfully added.</general>
    <withErrors>false</withErrors>
  </messages>
  <data>
    <prospect id="123"> 
      <createdByUserID>23</createdByUserID>
      <createdDateTime>2012-12-01 09:44:33</createdDateTime>
      <recruiterID>54</recruiterID>
      <locationID>1</locationID>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <expectedRevenue>0.0</expectedRevenue> 
      <expectedRevenueProbability>0.0</expectedRevenueProbability>  
    </prospect>
  </data> 
</response>

The API will respond will both an HTTP status code as well as provide feedback using messages embedded in the response.

GET

Now if we wanted to get that prospect at a later time:

https://username:password@abcschool.ampeducator.com/api/v1/prospects/123

Response:

<response statusCode="200" statusMessage="OK" method="GET">

  <metaData/>
  <messages> 
    <withErrors>false</withErrors>
  </messages>
  <data>
    <prospect id="123"> 
      ...
    </prospect>
  </data> 
</response>

Note that if no method is specified, it is assumed to be GET. If we want to get all prospects with say a status of 'Lead':

https://username:password@abcschool.ampeducator.com/api/v1/prospects?currentStatus=Lead&limit=3

Response:

<response statusCode="200" statusMessage="OK" method="GET">

  <metaData>
    <currentRecord>3</limit>
    <totalRecords>453</totalRecords>
    <criteria>currentStatus=Lead;LIMIT 0,10</criteria>
  </metaData>
  <messages>
    <withErrors>false</withErrors>
  </messages>
  <data>
    <prospects>
      <prospect id="342">
      ....
      </prospect>
      <prospect id="122">
      ....
      </prospect>
      <prospect id="432">
      ....
      </prospect>
    </prospects>
  </data>
</response>

In addition to responding with the data the api will also provide additional information about the result in the metaData section of the response.

PUT

We can also update the prospect by specifying the changed fields. For example to update where this prospect's expected revenue:

https://username:password@abcschool.ampeducator.com/api/v1/prospects/123?method=PUT&expectedRevenue=5500.00&expectedRevenueProbability=75.00

Response:

<response statusCode="200" statusMessage="OK" method="PUT">

  <metaData/>
  <messages>
    <general>Prospect was successfully updated.</general>
    <withErrors>false</withErrors>
  </messages>
  <data>
    <prospect id="123">
      ...
      <expectedRevenue>5500.00</expectedRevenue>
      <expectedRevenueProbability>75.00</expectedRevenueProbability>
    </prospect>
  </data>
</response>

DELETE

Lastly we can delete the prospect.

https://username:password@abcschool.ampeducator.com/api/v1/prospects/123?method=DELETE

The result being:

<response statusCode="200" statusMessage="OK" method="DELETE">
  <metaData/>
  <messages>
    <general>The prospect was successfully deleted.</general>
    <withErrors>false</withErrors>
  </messages>
  <data>
    <prospect>
      <prospectID>123</prospectID>
    </prospect>
  </data>
</response>

These are the basics. In these examples we've used the 'method' parameter to tell the API how it should handle the request but the API ca also determine the method from the HTTP Request Method (i.e. POST,GET,PUT,DELETE). Continue reading to find out all the details.

Setup & Authentication

In order to use the api an administrator must enable it through the Institution module in the ampEducator application. When enabling the API a username, password and optionally an email configuration must be made. Each request to the API must then include this authorization string. While there are more secure methods like oAuth we felt the complexity involved for the end developer was not justified. Basic authorization over HTTPS is essentially the same level of security which we provide to regular admins and the API has pretty much the same level of access as an administrator. For more information on HTTP Basic Authentication please see http://en.wikipedia.org/wiki/Basic_access_authentication.

Endpoint URL

The api can be accessed at https://purl.ampeducator.com/api/v1/endpoint where purl is the purl of your institution and the endpoint is one of the endpoints available. Only access through HTTPS is available and currently there is only v1 of the API.

Parameters

In order to make the api as useful and flexible as possible the following parameters are accepted. In cases where they do not apply they will be ignored by the API. All parameters are optional.

• method
  • If specified this will override the HTTP method being used. Acceptable values are 'POST', 'GET', 'PUT', 'DELETE'.
  • Example: method=POST

• suppressStatusCode
  • If set to 'true' the api will always return an HTTP Response Code of 200 OK even in cases of error. The response code will still be available in the response.
  • Example: supressStatusCode=true

• reponseType
  • By default the api will return the response as a JSON string however the response can also be returned as an XML document. Acceptable values are 'json', 'xml'.
  • Example: responseType=xml

• limit
  • When retrieving multiple records, the number of records will be limited by this parameter. Acceptable value is a positive integer. A value of 0 disables limit and is the default behaviour.
  • Example: limit=50

• offset
  • By combining limit and offset you can effectively retrieve pages of records. Offset will start retrieving records offset from the beginning by the amount specified. Acceptable value is a positive integer. A value of 0 disables offset and is the default behaviour. Offset will have no affect if a limit is not set as well.
  • Example: offset=100

• fields
  • Sometimes you only need certain fields of an object. When the field parameter is specified only the specified fields are populated. Acceptable value is a comma delimited list of fields.
  • Example: fields=firstName,lastName,status

• orderBy
  • If you need results in ordered you can specify the ordering by using this parameter. Acceptable value is a comma delimited list of fields you would like to order by. When this parameter is not specified the ordering is usually by the id field of the object although this is not guaranteed.
  • Example: orderBy=dateOfBirth,lastName

• orderDir
  • When using orderBy you can specify the order direction for each field using the orderDir parameter. Acceptable is a comma delimited list of 'asc' and 'desc'. By default the ordering will be ascending.
  • Example: orderDir=desc,asc

Dates & Times

The API expects all dates and times to be in 24hr mySql format.

• Date: YYYY-MM-DD
• Time: HH:mm:ss
• DateTime: YYYY-MM-DD HH:mm:ss

Encoding

The API expects all incoming data to be encoded as UTF-8.