Office Hawk API

Welcome to the Office Hawk API docs!

We're watching you...

Methods

• Organization Methods

  • Registration
  • Editing
  • Deleting
  • Listing Registered Orgs

• Employee Methods

  • Login
  • Registration
  • List Employees
  • List Employee Alerts
  • Update Employee
  • Delete Employee

• Alert Methods

  • New Alert
  • Delete Alert
  • Index of Alerts

• Beacon Methods

  • New Beacon
  • Beacon List
  • Editing a Beacon
  • Deleting a Beacon

##Organization Methods

###Registration

This request triggers creating a new organiztation as well as creating a new user who will be tagged as an admin.

URL /organizations

Method POST

Request

Parameter	Type	Description
username	String	​*(Required)*​ unique username. This will also become the owner of the org/team
password	String	​*(Required)*​ Password for the user
name	String	​*(Required)*​ Unique name of team/organization
email	String	Optional email address of owner

Response

If successful, you will receive:

Status Code: 201 - Created

    { "organization": 
            { "organization_id": 1,
              "name": "nameoforghere"
              "owner": "usernameofownerhere"
            }
       "auth_token": "The Auth Token for the Owner"
       "gravatar_url": "the image url for the email address of the owner"
    }
            

​*As long as you get the above, the owner user was also succeesfully created.*​

If unsuccessful, you will receive:

Status Code: 422 - Unprocessable Entity

    {"errors":[
                "Organization has already been taken",
                ]
    }

###Editing

Editing the owner and/or name of an organization. The :id in the route refers to the organization's unique id (organization.id)

NOTE: for owner parameter, the username must be EXACTLY THE SAME AS THE USERNAME USED TO REGISTER THE EMPLOYEE! Misspelled usernames will throw an error when trying to change owners/admins

URL /organizations/:id

Method PUT

Request

HEADERS:

auth-token (Required)

Parameter	Type	Description
name	String	​*(Required)*​ unique organization name
owner	String	​*(Required)*​ Username of the org owner
email	String	Optional email for org owner

Response

If successful, you will receive:

Nothing. And be thankful for it.

If unsuccessful, you will receive:

Status Code: 422 - Unprocessable Entity

    {"errors":[
                "What you messed up will be in here",
                ]
    }

###Deleting an Org

Deleting an org and all associated entities

URL /organizations

Method DELETE

Request

Parameter	Type	Description
organization_id	Integer	​*(Required)*​ The ID of the org you want to destroy

Response

If successful, you will receive:

A very sad message about how you destroyed everything.

If unsuccessful, you will receive:

A whole lot of nothing because really how could you screw this up?

###List All Organizations

Get a list of all registered organizations

URL /organizations

Method GET

Request

​*There are no parameters required for this request. Orgs are searchable by ID, Name and Owner (which will be a username from the Employees database)*​

Response

If successful, you will receive a list of all registered organizations:

Status Code: 200 - OK

    { "organization": 
            { "organization_id": 1,
              "name": "nameoforghere"
              "owner": "usernameofownerhere"
            }
    }
            

If unsuccessful, you will receive:

Probably nothing. Nobody has ever failed this.

##Employee Methods

###New

Sign up a new employee for your team/organization, must be logged in as an ADMIN user by providing their auth_token as a header

URL /employees

Method POST

Headers

auth_token (Required)

Request

Parameter	Type	Description
username	String	(Required) unique username per organization (within an organizations two users cannot have the same username)
password	String	(Requred) employee's password
email	String	Optional employee ID (Gravatar Profile Pics supported)

Response

If successful, you will receive:

Status Code: 201 - Created

{
  "success": "dan created successfully",
  "username": "dan",
  "auth_token": "f74ef72a9c26cc05ac181aab3083521f"
  "gravatar_url": "https://secure.gravatar.com/avatar/9432f06f93b436aad3926d4588780be8.png?r=PG"
}
			

If unsuccessful, you will receive:

Status Code: 422 - Unprocessable Entity

	{"errors":[
				"Username has already been taken",
				]
	}

###Login

Login an existing employee, gives you their auth_token and Gravatar profile pic (will default to a general pic if no email was provided)

URL /employees/login

Method POST

Request

Parameter	Type	Description
username	String	(Required) existing employee's username for the organiation id provided
password	String	(Requred) employee's password

Response

If successful, you will receive:

Status Code: 201 - Created

{
  "success": "dan logged in successfully",
  "username": "dan",
  "auth_token": "f74ef72a9c26cc05ac181aab3083521f"
  "gravatar_url": "https://secure.gravatar.com/avatar/9432f06f93b436aad3926d4588780be8.png?r=PG"
}
			

If unsuccessful, you will receive:

Status Code: 401 - Uauthorized

{
  "errors": "username or password incorrect"
}

###List Employees for an Org

List all employees for an organization

URL /employees

Method GET

Headers

auth-token (Required)

Request

Response

If successful, you will receive:

Status Code: 200 - OK

{
  "employees": [
    {
      "id": 3,
      "username": "terri"
      "gravatar_url": "https://secure.gravatar.com/avatar/9432f06f93b436aad3926d4588780be8.png?r=PG"

    },
    {
      "id": 4,
      "username": "mac"
      "gravatar_url": "https://secure.gravatar.com/avatar/9432f06f93b436aad3926d4588780be8.png?r=PG"
    }
  ]
}
			

If unsuccessful, you will receive:

Status Code: 422 - Unprocessable Entity

{
  "errors": "username or password incorrect"
}

###Display Employee Alert Data

Display all alerts for a given employee ID

URL /employees/:id

Method GET

Headers

auth-token (Required)

Request

Response

If successful, you will receive:

Status Code: 200 - OK

{
  "alert": [
    {
      "id": 1,
      "state": "near",
      "beacon_id": 4,
      "beacon_uuid": "4B91A9DF-B7D0-CBA4-096B-9EAE45837F02",
      "beacon_minor": "1000",
      "beacon_major": "100",
      "duration": 20
    },
    {
      "id": 2,
      "state": "far",
      "beacon_id": 4,
      "beacon_uuid": "4B91A9DF-B7D0-CBA4-096B-9EAE45837F02",
      "beacon_minor": "1000",
      "beacon_major": "100",
      "duration": 20
    },
    {
      "id": 3,
      "state": "near",
      "beacon_id": 4,
      "beacon_uuid": "4B91A9DF-B7D0-CBA4-096B-9EAE45837F02",
      "beacon_minor": "1000",
      "beacon_major": "100",
      "duration": 20
    }
  ]
}
			

If unsuccessful, you will receive:

Status Code: 401 - Unauthorized

{
  "errors": "you betta be logged in to do that!"
}

###Update Employee

Update employee username, must be logged in as an ADMIN user by providing their auth_token as a header

URL /employees/:employee_id

Method PUT

Headers

auth-token (Required)

Request

Parameter	Type	Description
username	String	(Required) whatever you want to change the username to
email	String	Optional email (tied to gravatar profile pic)

Response

If successful, you will receive:

Status Code: 200 - OK

{
  "success": "Employee updated successfully"
}		

If unsuccessful, you will receive:

Status Code: 401 - Unauthorized

{
  "errors": "You don't have permission to update that employee"
}

###Delete Employee

Delete an employee from a team/org and any associated data, must be logged in as an ADMIN user by providing their auth_token as a header

URL /employees/:employee_id

Method DELETE

Request

Headers

auth-token (Required)

Response

If successful, you will receive:

Status Code: 200 - OK

{
  "success": "Employee delete successfully"
}		

If unsuccessful, you will receive:

Status Code: 401 - Unauthorized

{
  "errors": "You don't have permission to delete that employee"
}

##Alert Methods

###New Alert

This logs the alert for a given employee. This is triggered when an employee enters the range of a beacon and/or moves closer or further from it.

URL /alerts

Method POST

Request

Headers

auth-token (Required)

Parameter	Type	Description
uuid	integer	​*(Required)*​ The UUID for the beacons
major	String	​*(Required)*​ Customizable in V2.0
minor	String	​*(Required)*​ Customizable in V2.0
state	String	(Required) Signifies the distance from the beacon the employee is. Sent from the beacons.
duration	integer	(Required) Length of time in seconds an employee has been in a given zone

Response

If successful, you will receive:

A colorful message about how great you've done.   

If unsuccessful, you will receive:

A whole bunch of gibberish you probably won't understand.  Try not to ask too many questions.  It will be in json format.

###Deleting an Alert

In the EXTREMELY rare occurrance you need to delete an alert - for instance, to cover your tracks because you are an unethical tyrant - this method provies the ability to do so. Deletes an alert from the databas.

URL /alerts

Method DELETE

Request

Headers

auth-token (Required)

Response

If successful, you will receive:

Nothing.  Absolutely nothing. 

If unsuccessful, you will receive:

A stern talking to because how could you screw this up?

###Index of Alerts

For displaying all active alerts and updates. This is where the bulk of the work and information is displayed.

URL /alerts

Method GET

Request

Headers

auth-token (Required)

Response

If successful, you will receive:

A bunch of code.

If unsuccessful, you will receive:

An error message telling you exactly what you screwed up, you amateur.  

##Beacon Methods

###Adding a new Beacon

This allows you to add a new beacon to your organization, which will allow you to track alerts from a new zone.

NOTE: Major and Minor can be considered equivalent to "room" and "place in the room".

For example: MAJOR = Kitchen, Minor = Coffee Maker

URL /beacons

Method POST

Request

Headers

auth-token (Required)

Parameter	Type	Description
uuid	String	​*(Required)*​ The UUID of the beacon
major	String	​*(Required)* The major identifier, customizable in V2.0
minor	String	​*(Required)*​ The minor identifier, customizable in V2.0
organization_id	integer	(Required) The id of the organization the beacons are registered to

Response

If successful, you will receive:

Status Code: 201 - Created

json.success "Beacon created successfully"
json.beacon_id @beacon.id            

If unsuccessful, you will receive:

Status Code: 422 - Unprocessable Entity

    {"errors":[
                "YOU FUCKED UP",
                ]
    }

###Edit a Beacon

This will return a list of all organization-registered beacons and their associated information.

URL /beacons/:id

Method PUT

Request

Headers

auth-token (Required)

Parameter	Type	Description
uuid	String	​*(Required)*​ The UUID of the beacon
major	String	​*(Required)* The major identifier, customizable in V2.0
minor	String	​*(Required)*​ The minor identifier, customizable in V2.0
organization_id	integer	(Required) The id of the organization the beacons are registered to

Response

If successful, you will receive:

json: { success: "Beacon updated successfully" }, status: :ok
        

If unsuccessful, you will receive:

Status Code: 404

    {"errors":[
                "YOU FUCKED UP.  Check your parameters and try again.
                ]
    }

###List of all Beacons

This will return a list of all organization-registered beacons and their associated information.

URL /beacons

Method GET

Request

Response

If successful, you will receive:

json.beacons do
  json.array!(@beacons) do |beacon|
    json.extract! beacon, :id, :uuid, :major, :minor
  end
end
        

If unsuccessful, you will receive:

Status Code: 404

    {"errors":[
                "YOU FUCKED UP.  Probably aren't looking for the right things...or you aren't authorized.  Either way, the Hawk has been notified.  Run while you can.",
                ]
    }

###Delete a Beacon

In the event you need to delete a beacon, this is the way to do it.

URL /beacons/:id

Method DELETE

Request

Parameter	Type	Description
beacon_id	integer	​*(Required)*​ The unique ID of the beacon you'd like to delete

Response

If successful, nothing happens. What, you want a pretty status message or something?

If unsuccessful, you should probably not be messing around with back-end commands, fam.