Changelog
Start typing to search…
Back to All
added

API v1 Beta now available for all customers

about 1 year ago by Tony Rule
  • Added tags on response to GET /projects
  • Added includePlaceholders filter for GET /people
  • Added GET /projects/:id/people
  • Replaced GET /milestones with GET /projects/:id/milestones
  • API v1 beta release notes

See API v1 usage instructions. While the API v1 is still in beta this changelog is a living document.

v1.0.0

URL

The base URL for using API v1 is https://api.runn.io (this has changed from v0).

Note: Refer to “Accounts > Settings > API” for your specific API endpoint URL, it might differ from the above.

Accept-Version Header

We now require passing an Accept-Version header, specifying the version of the API you’d like to use.

Example: Accept-Version: 1.0.0

Pagination

Changed from page-based to cursor-based pagination. Instead of per_page, use limit. Instead of page, use the cursor provided as nextCursor in the previous API response.

Identifiers

We've switched from hashids to numeric identifiers to identify resources.

Before:

/v0/people/156ocz

After:

/people/123

In order to convert existing references to the new format, we have provided a /legacy-id endpoint.

To convert the example above, use the following request:

GET /legacy-id/people/156ocz

You also have the option to convert these values locally for better performance.

Here's an example Python implementation, which you can adapt to a programming language of your choice (using one of the many implementations on hashids.org).

Naming Format

  • Changed all property and parameter names from lower snakecase to camelcase: person_id becomes personId
  • Changed endpoint paths from snakecase to dashcase. Example: GET /v0/time_offs becomes GET /time-offs

Request and Response Structure

  • Dropped the /v0 prefix on paths
  • Changed HTTP verbs from PUT to PATCH
  • Collection endpoint results are nested in a {values: []} object

References Format

Changed references format on all endpoints.

Before:

{
  "My Name": {"external_id": "My ID"},
  "My Other Name": {"external_id": "My Other ID"}
}

After:

[
  {"referenceName": "My Name", "externalId": "My ID"},
  {"referenceName": "My Other Name", "externalId": "My Other ID"}
]

Tags Format

Changed tags format on all endpoints. Retrieve tag identifiers from GET /project-tags.

Before:

["My Tag", "My Other Tag"]

After:

[{id: 1}, {id: 2}]

Endpoint Specific Changes

  • GET /invitations: sentDate attribute renamed to sentAt
  • POST /actuals: No longer allows clearing phases with empty strings, requires phaseId=null
  • POST /actuals: No longer auto-fills gaps (autofill=true)
  • GET /actuals: Date filtering parameters renamed to minDate and maxDate
  • GET /actuals: No longer returns updated_at or origin_data
  • GET /assignments: Renamed date filtering parameters to startDate and endDate
  • GET /assignments: No longer returns total_minutes, use Reporting API instead
  • GET /assignments: Renamed active to isActive
  • GET /clients: Removed include_archived filter
  • GET /clients, POST /clients: Removed projects
  • GET /clients: Renamed url to website
  • GET /clients, POST /clients, PATCH /clients: Renamed archived to isArchived
  • GET /contracts: Changed rostered_days to availableDays (keyed by weekday name)
  • GET /milestones, POST /milestones, DELETE /milestones: Moved into /projects/:id/milestones subresource
  • GET /milestones: Renamed date filtering parameters to startDate and endDate
  • GET /people: Moved role_id and role_name to GET /people/:id/contracts/current
  • GET /people, GET /people/:id: Moved team_id and team to GET /people/:id/teams
  • GET /people, GET /people/:id: Moved current_contract to GET /people/:id/contracts/current
  • GET /people, GET /people/:id: Moved projects to GET /people/:id/projects, removed include_projects parameter
  • GET /people, GET /people/:id: Moved skills to GET /people/:id/skills
  • GET /people: Removed include_placeholders option, use GET /placeholders
  • GET /people/:id: Moved assignments to GET /people/:id/assignments, removed include_assignments, start and end parameters
  • GET /people/:id: Moved actuals to GET /people/:id/actuals, removed include_actuals, start and end parameters
  • GET /people/:id: Moved skills to GET /people/:id/skills, removed skills_unstable
  • GET /people/:id: Moved time_offs to GET /people/:id/time-offs
  • GET /people/:id: Moved holidays_unstable to GET /people/:id/time-offs/holidays
  • GET /people, GET /people/:id: Rename people_notes to notes
  • GET /people: Renamed archived to isArchived
  • POST /people: Removed role_name, use role_id
  • GET /phases: Moved to GET /projects/:id/phases
  • POST /placeholders: Create placeholders so you can then create assignments for placeholders on projects (retaining functionality from v0)
  • GET /project_notes: Moved to GET /projects/:id/notes
  • POST /project_notes: Moved to POST /projects/:id/notes
  • POST /project_notes: Removed ability to set user_id, defaults to “API” user
  • GET /projects: Includes template projects by default (filter manually based on isTemplate property)
  • GET /projects/:id: Moved assignments to GET /projects/:id/assignments, removed include_assignments option
  • GET /projects/:id: Moved actuals to GET /projects/:id/actuals, removed include_actuals option
  • GET /projects/:id: Moved milestones to GET /projects/:id/milestones
  • GET /projects/:id: Moved other_expenses to GET /projects/:id/other-expenses
  • GET /projects/:id: Moved project_rates to GET /projects/:id/project-rates
  • GET /projects/:id: Moved phases to GET /projects/:id/phases
  • GET /projects/:id: Moved timesheet_locked_to to GET /projects/:id/timesheet-lock
  • GET /projects/:id/people: retaining functionality from v0
  • POST /projects, PATCH /projects/:id: Removed project_rates
  • POST /projects, PATCH /projects/:id: Renamed confirmed to isConfirmed
  • POST /projects/:id/project-rates and PATCH /projects/:id/project-rates
  • PUT /projects/:id/lock_timesheets: Moved to PATCH /projects/:id/timesheet-lock
  • GET /rate-cards: Changed blended_rate_hourly and blended_rate_daily to blendedRate and rateType
  • GET /rate-cards: Renamed archived to isArchived
  • POST /roles, PATCH /roles: Changed people to personIds
  • POST /skills/:id/people: retaining functionality from v0
  • GET /teams, POST /teams, PATCH /teams/:id: Removed people, use /people/:id/teams to identify and modify team membership
  • GET /time-offs: Removed type, split into separate subresources: GET /time-offs/leave, GET /time-offs/rostered-off.
  • GET /time_offs/holidays_unstable: Moved to GET /time-offs/holidays
  • GET /users: Changed permissions from serialised JSON strings to an actual object

Unreleased

We’re still working on these endpoints:

  • POST /invitations: Requires fromUser (no longer defaulting to first admin)
  • GET /placeholders
  • GET /people-tags/:id: See all people who have this tag
  • GET /clients/:id/projects
  • POST /projects/:id/other-expenses and PATCH /projects/:id/other-expenses/:id

New

  • GET /assignments: isTemplate and active
  • /custom-fields endpoints
  • Add customFields to GET /people/:id and GET /projects/:id
  • List public holidays separately from people through /holiday-groups
  • GET /projects: isTemplate, expensesBudget
  • GET /rate-cards: List projectIds
  • New reports API: GET /reports/*
  • /project-tags endpoints