Roadmap

• What
• Why
• How
• At shyftplan

API stands for ...

• Application
• Programming
• Interface

What can i do with an API?

Import Data

• 

• ▶

• 

Export Data

• 

• ◀

• 

Write Commands

• 

• ▶

• 

Add notifications

• 

• ◀

• 

Why do i need an API for that?

• 

• // ISO 8601
  "2018-02-28T07:00:00.000+01:00"

• 

• 33291

How does the data from

the API look like?

• 

• {
    "id": 6359714
  }

• 

• {
    "id": 6359714
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00"
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00"
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00"
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00"
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4,
    "can_evaluate": true
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4,
    "can_evaluate": true
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4,
    "can_evaluate": true
  }

• 

• {
    "id": 6359714,
    "locations_position_id": 33291,
    "starts_at": "2018-02-28T07:00:00.000+01:00",
    "ends_at": "2018-02-28T15:30:00.000+01:00",
    "workers": 4,
    "can_evaluate": true,
    "note": "We need to do a release today"
  }

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

{
  "id": 6359714,
  "locations_position_id": 33291,
  "starts_at": "2018-02-28T07:00:00.000+01:00",
  "ends_at": "2018-02-28T15:30:00.000+01:00",
  "workers": 4,
  "can_evaluate": true,
  "note": "We need to do a release today"
}

How to get the data?

API Playground

API Action

• HTTP Method
• URL
• Parameters

HTTP Method

• POST        // create

• GET         // read

• PUT / PATCH // update

• DELETE      // delete

URL

• POST   /api/v1/shifts

• GET    /api/v1/shifts

• GET    /api/v1/shifts/{id}

• PUT    /api/v1/shifts/{id}

• DELETE /api/v1/shifts/{id}

Parameters

• ?key1={value1}&key2={value2}&key3={value3}

• ?user_email={email}&authentication_token={token}

• ?ids[]={id1}&ids[]={id2}

API Playground

Authentication

• Needed for every call
• With Email

Authentication

• Needed for every call
• With Email & Authentication Token

Authentication Token

• Can be generated on Employment Profile
• Or can be fetched with Email and Password

API Playground

Models

User

• Stores the login data

User

{
  "id": 1337,             // Id of User
  "email": "tamino@...",  // Login mail address
  "created_at": ...,
  "updated_at": ...,      // Timestamps
  "deleted_at": ...
}

Employment

• Connects Companys with Users

Employment

"id": 1337,             // Id of Employment
"user_id": 4711,        // Id of User
"company_id": 54,       // Id of Company
"is_employee": true,    // Is the user an employee?
"is_stakeholder": true, // Is the user an stakeholder?
"first_name": "Foo",    // First Name
"last_name": "Bar",     // Last Name

Position

• Every Company can have multiple Positions.

Position

"id": 1337,             // Id of Position
"company_id": 54,       // Id of Company
"name": "Foo",          // Position Name
"description": "",      // Descripton
"color": "#aaeee1",     // Background color
"sort": 13,             // Used to order them
"text_color": "#000",   // Foreground color (black / white)
"note": ""              // Position Note

Location

• Every Company can have multiple Locations.

Location

"id": 1337,             // Id of Location
"company_id": 54,       // Id of Company
"name": "Foo",          // Position Name
"sort": 13,             // Used to order them

LocationsPosition

• Connects Locations with Positionss.

LocationsPosition

"id": 1337,             // Id of LocationsPosition
"location_id": 4711,    // Id of Location
"position_id": 815,     // Id of Position
"sort": 13,             // Used to order them

EmploymentsPosition

• Connects Employments with LoctionsPositions.

EmploymentsPosition

"id": 1337,             // Id of EmploymentsPosition
"employment_id": 4711,  // Id of Location
"locations_position_id": 815, // Id of LoctionsPosition

Shiftplan

• Collection of Shifts and related to an Location.

Shiftplan

"id": 1337,             // Id of Shiftplan
"location_id": 58,      // Id of Location
"starts_at": "yyyy-mm-dd", // Shiftplan goes from this date
"ends_at": "yyyy-mm-dd",   // to this date (both included)
"state": "published",   // State (published/unpublished)
"name": "Foo",          // Shiftplan name

Shift

• Defines an working slot for an defined amount of Employments.
• A shift is connected to an Position on the Shiftplans Location.

Shift

"id": 1337,             // Id of Shift
"shiftplan_id": 4711,   // Id of Shiftplan
"locations_position_id": 815, // Id of LocationsPosition
"starts_at": "...",     // Shift goes from this time
"ends_at": "...",       // to this time (ISO 8601 format)
"workers": 1,           // Maximum amount of workers
"break_time": 0,        // Duration of breaks (in minutes)
"can_evaluate": true,   // Can be evaluated by employees
"note": null,           // Shift Note
"untimed": false,       // If shifts time counted?
"manager_note": null    // Manager Note

StaffShift

• Connects Employments with Shifts.

StaffShift

"id": 1337,             // Id of StaffShift
"shift_id": 4711,       // Id of Shift
"employment_id": 815,   // Id of Employment
"state": "no_evaluation", // Current Evaluation state
                          // - no_evaluation
                          // - done_evaluation
                          // - needs_evaluation
                          // - punchtimed
                          // - no_show
"total_minutes": 241,   // Working time (without break)
"total_payment": 50.21  // Sum of all payments

Request

• Connects Employments with Shifts.

Request

"id": 1337,             // Id of Request
"shift_id": 4711,       // Id of Shift
"employment_id": 815,   // Id of Employment
"type": "StaffRequest"  // Type of Request
                        // - StaffRequest
                        // - ChangeRequest

Evaluation

"id": 1337,             // Id of StaffShift
"shift_id": 4711,       // Id of Shift
"employment_id": 815,   // Id of Employment
"locations_position_id": 54, // Id of LocationsPosition
"shiftplan_id": 136,    // Id of Shiftplan
"location_id": 58,      // Id of Location
"position_id": 96,      // Id of Position
"user_id": 405,         // Id of User
"first_name": "Foo",    // First Name of Employment
"last_name": "Bar",     // Last Name of Employment

"evaluation_starts_at": ..., // Evaluated Start of Shift
"evaluation_ends_at": ...,   // Evaluated End of Shift
"evaluation_break": 0,       // Break time in minutes
"evaluation_duration": 330,  // Working time in minutes
"state": "no_evaluation",    // State of Evaluation
"shift_note": null,               // Shift note
"admin_evaluation_note": null,    // Stakeholder Note
"employee_evaluation_note": null, // Employee Note

"position": {
  "name": "Foo"        // Position Name
},
"location": {
  "name": "Bar"        // Location Name
},
"shift": {
  "starts_at": ...,    // Planned Shift Start
  "ends_at": ...,      // Planned Shift End
  "break_time": 0      // Planned Shift Break Time
}

API Playground

Open inspector

⌘ + ⌥ + i

Fetch URL

• Read data

  $.get('{url}', console.log);

• Create data

  $.put('{url}', console.log);

• Delete / Update data

  $.ajax('{url}', { options });

Save data

• var data;

• $.get('{url}', res => data = res);

• data

• data.items

Play around

• _.pluck(data.items, 'id')

• _.groupBy(data.items, 'state')

• _.sum(data.items, 'total_payment')

Thats it

Whats next?

• API Playground
• shyftplan.com/swagger
• Slides
• lets-talk-about--api.taminomartinius.de