apiary.apib

FORMAT: 1A

# TimeEntry api
TimeEntry API is a time entry service.

# Group BookedTimeEntry
TimeEntry related resources of the **TimeEntry API**

## BookedTimeEntry List [/booked-time-entries{?start_date,end_date}]

### List all BookedTimeEntries [GET]
+ Parameters

    + start_date (optional, date, `2014-05-05`) ... Date `start_date` of the BookedTimeEntry. Has example value.
    + end_date (optional, date, `2014-05-05`) ... Date `end_date` of the BookedTimeEntry. Has example value.
    
+ Request

    + Header
            
            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json
            If-None-Match: W/"11-2535484157"

+ Response 200 (application/json)

    + Header
        
            Request-Id: <UUID>
            ETag: W/"11-2535484157" 
        
    + Body

            [{
              "id": 1, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Wednesday.", "read_only": false,
              "allocation": { "id": 2, "client": "State of Minnesota DEED", "project": "MN Works", "task": "Development" }
            }, {
              "id": 2, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Thursday.", "read_only": true,
              "allocation": { "id": 2, "client": "Agribank", "project": "Titaniun", "task": "Testing" }
            }]
            
## Your BookedTimeEntry List [/me/booked-time-entries{?start_date,end_date}]

### List all your BookedTimeEntries [GET]
+ Parameters

    + start_date (optional, date, `2014-05-05`) ... Date `start_date` of the BookedTimeEntry. Has example value.
    + end_date (optional, date, `2014-05-05`) ... Date `end_date` of the BookedTimeEntry. Has example value.
    
+ Request

    + Header
            
            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json
            If-None-Match: W/"11-2535484157"

+ Response 200 (application/json)

    + Header
        
            Request-Id: <UUID>
            ETag: W/"11-2535484157" 
        
    + Body

            [{
              "id": 1, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Wednesday.", "read_only": false,
              "allocation": { "id": 2, "client": "State of Minnesota DEED", "project": "MN Works", "task": "Development" }
            }, {
              "id": 2, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Thursday.", "read_only": true,
              "allocation": { "id": 2, "client": "Agribank", "project": "Titaniun", "task": "Testing" }
            }]            

## BookedTimeEntry [/booked-time-entries]

### Create a BookedTimeEntry [POST]
+ Request (application/json)

    + Header

            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json

    + Body

            { "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-07", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }

+ Response 201 (application/json)
    
    + Header
        
            Request-Id: <UUID>
    
    + Body

            { "id": 3, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-07", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }

## BookedTimeEntry [/me/booked-time-entries]

### Create a BookedTimeEntry for yourself [POST]
+ Request (application/json)

    + Header

            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json

    + Body

            { "date": "2014-05-07", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }

+ Response 201 (application/json)
    
    + Header
        
            Request-Id: <UUID>
    
    + Body

            { "id": 3, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-07", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }




## BookedTimeEntry [/me/booked-time-entries/{id}]
A single BookedTimeEntry object with all its details

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the BookedTimeEntry to perform action with. Has example value.

### Update a BookedTimeEntry for Yourself [PUT]
+ Request (application/json)

    + Header

            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json

    + Body

            { "id": 1, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Saturday.", "allocation": { "id": 1 } }

+ Response 200

    + Header
        
            Request-Id: <UUID>
            
    + Body

            { "id": 3, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }            

### Remove a BookedTimeEntry for Yourself [DELETE]
+ Response 200

    + Header
        
            Request-Id: <UUID>
            
    + Body

            { "id": 3, "user": { "id": "31EC2020-3AEA-4069-A2DD-08002B30309D" }, "date": "2014-05-10", "hours": 8, "note": "I worked all day long on Friday.", "allocation": { "id": 1 } }            

# Group Allocation
Allocation related resources of the **TimeEntry API**

## Allocation Collection [/allocations]

### List all Allocations [GET]

+ Request

    + Header
            
            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json
            If-None-Match: W/"11-2535484157"
            
+ Response 200 (application/json)
    
    + Header
        
            Request-Id: <UUID>
            ETag: W/"11-2535484157" 
    
    + Body
    
            [{
              "id": 1, "client": "Magic Muffin Factory", "project": "MN Works", "task": "Development", "active": true, "billable": true, "isIntertech": false
            }, {
              "id": 2, "client": "Acme Inc", "project": "Titaniun", "task": "Testing", "active": false, "billable": true, "isIntertech": false
            }]

## Your Allocation Collection [/me/allocations]

### List all your Allocations [GET]

+ Request

    + Header
            
            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json
            If-None-Match: W/"11-2535484157"
            
+ Response 200 (application/json)
    
    + Header
        
            Request-Id: <UUID>
            ETag: W/"11-2535484157" 
    
    + Body
    
            [{
              "id": 1, "client": "Magic Muffin Factory", "project": "MN Works", "task": "Development", "active": true, "billable": true, "isIntertech": false
            }, {
              "id": 2, "client": "Acme Inc", "project": "Titaniun", "task": "Testing", "active": false, "billable": true, "isIntertech": false
            }]

## Allocation [/allocations/{id}]
A single Allocation object with all its details

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the Allocation to perform action with. Has example value.

### Retrieve an Allocation [GET]
+ Request

    + Header
            
            Authorization: Bearer <token>
            Accept: vnd.intertech.v1+json
            If-None-Match: W/"11-2535484157"


+ Response 200 (application/json)
    + Header
        
            Request-Id: <UUID>
            ETag: W/"11-2535484157" 
    
    + Body

            { "id": 1, "client": "State of Minnesota DEED", "project": "MN Works", "task": "Development" }

## Me [/me]
Information about yourself

## Retrieve your user object [GET]

+ Request

    + Header
    
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
            
+ Response 200 (application/json)
            
    + Header
    
            Request-Id: <UUID>
    
    + Body
            
            { "name": "Luke", "email": "luke@gmailx.com" }
            

# Group Authentication
Authentication endpoints

## Token [/token]
Authentication Endpoint to get a bearer token for use in other api endpoints.

## Retrieve a token via SAML [POST]

+ Request

    + Header
    
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
    + Body
    
            { "grant_type": "saml", "token": "--base64 encoded token--" }
            
+ Response 200 (application/json)

    + Header
    
            Request-Id: <UUID>
    
    + Body
            
            { "access_token": "--bearer token--", "token_type": "bearer", "name": "Luke Vader", "email": "a@b.c" }
            
## Retrieve a token via Password [POST]

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
    
    + Body
    
            { "grant_type": "password", "username": "Luke", "password": "theforce" }
            
+ Response 200 (application/json)

    + Header
    
            Request-Id: <UUID>
    
    + Body
            
            { "access_token": "--bearer token--", "token_type": "bearer", "name": "Luke Vader", "email": "a@b.c" }
    
# Group Notifications    
            
## Your Notifications [/me/notifications]

## List your device registrations [GET]

List all of your device registrations, deviceToken means it is apple, gcmRegistrationId indicates google

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
            
+ Response 200 (application/json)

    + Header
    
            Request-Id: <UUID>

    + Body
    
            [{"id":"123","deviceToken":"4456588DEAR", "gcmRegistrationId": "123456","expires":"2015-06-10T03:54:34.282Z"}]
          
## Your Apple Devices [/me/notifications/apns]

## Register new Apple device [POST]          

Registers a new APNS device

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json

    + Body
    
            {"deviceToken": "4456588DEAR"}
        
+ Response 201 (application/json)

    + Header
    
            Request-Id: <UUID>

    + Body
    
            {"id":"123","deviceToken":"4456588DEAR","expires":"2015-06-10T03:54:34.282Z"}

## Your Google Devices [/me/notifications/gcm]
            
## Register new Google device [POST]          

Registers a new GCM device

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json

    + Body
    
            {"gcmRegistrationId": "4456588DEAR"}
        
+ Response 201 (application/json)

    + Header
    
            Request-Id: <UUID>

    + Body
    
            {"id":"123","gcmRegistrationId":"4456588DEAR","expires":"2015-06-10T03:54:34.282Z"}            

## Device Registration [/me/notifications/{id}]
            
## Delete device [DELETE]

Delets a registered device

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
            
+ Response 204 (application/json)

    + Header
    
            Request-Id: <UUID>
            
## Test Notification [/me/notifications/actions/send]

## Send Test Notification [POST]

Sends a test notification to all of your registered devices

+ Request

    + Header
        
            Accept: vnd.intertech.v1+json
            Content-Type: application/json
            
    + Body
    
            {"message": "test notification","count": 100}
            
            
+ Response 204 (application/json)
            
    + Header
    
            Request-Id: <UUID>