Migrate from API 1.0 to API 2.0


Vector.png

The old navigation will be removed from Jira Align in early 2024.
Learn more about the upcoming changes


API 1.0 will be removed from Jira Align in version 10.130.0, which is scheduled for February 16, 2024. We encourage you to migrate your integrations, queries, and other API calls to API 2.0 soon to prepare for this change. Use the following info to migrate to API 2.0.

On this page:

Authentication changes

API 2.0 requires a different API token that can be found and generated in the user profile menu, below the API v1 token:

APItokens.png

URL changes

URL paths change slightly when using API 2.0. For example, consider the Users endpoint:

Endpoint changes

Review the table below to see how endpoints are affected between API 1.0 and API 2.0:

API 1.0 endpoint

API 2.0 endpoint

Notes

Users Users Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
Cities Cities Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
Regions Regions Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
ReleaseVehicles ReleaseVehicles Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
Tasks Tasks Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
Teams Teams Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
CostCenters CostCenters Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
WorkCodes WorkCodes Same endpoint name. Attribute keys have been renamed to adhere to 2.0 standards
EmpClass N/A Not available in API 2.0. Contact Jira Align Support if needed.
Holidays N/A Not available in API 2.0. Contact Jira Align Support if needed.
OrganizationStructures N/A Not available in API 2.0. Contact Jira Align Support if needed.
PayPeriods N/A Not available in API 2.0. Contact Jira Align Support if needed.
TaskDetails N/A Not available in API 2.0. Contact Jira Align Support if needed.
Timesheets N/A Not available in API 2.0. Contact Jira Align Support if needed.
ValueEngineering N/A Not available in API 2.0. Contact Jira Align Support if needed.
WorkHours N/A Not available in API 2.0. Contact Jira Align Support if needed.


Headers

Basic authentication headers are not supported. Review the Authentication changes section above.

Query parameters

API 2.0 supports powerful query capabilities. Refer to the documentation for more info regarding $select, $top, $skip, $orderby, and $filter parameters. If you use existing API 1.0 query parameters, which are endpoint specific, you will need to rewrite your queries to use the generic API 2.0 query parameters.

Payload changes

Please refer to the API 1.0 and API 2.0 documentation to map the attributes of each endpoint.

The collection response format is the most significant change between 1.0 and 2.0:

  • API 1.0 returns an object containing an array of entities.
    • {
      "Filter": null,
      "TotalResults": 924,
      "Results": [
      {
      "ID": 1,
      "Name": "Washington DC Area",
      "RegionID": 1,
      "LastModified": "2019-09-22T14:58:44",
      "Image": "DC",
      "ApplyTimeTracking": true
      },
      ...
      {
      "ID": 988,
      "Name": "City 0XW972ZLNPHK9O42AS",
      "RegionID": 1358,
      "LastModified": "2023-12-11T12:39:40.657",
      "Image": null,
      "ApplyTimeTracking": false
      }
      ],
      "Self": "/api/Cities/"
      }
  • API 2.0 returns an array. 
    • [
      {
      "id": 1,
      "name": "Washington DC Area",
      "regionId": 1,
      "lastUpdatedDate": "2019-09-22T14:58:44Z",
      "applyTimeTracking": true,
      "image": "DC",
      "self": "https://environmentname.jiraalign.com/rest/align/api/2/cities/1"
      },
      ...
      {
      "id": 108,
      "name": "City DRHVKDMSHLP8EAG428",
      "regionId": 125,
      "lastUpdatedDate": "2023-11-10T05:31:39Z",
      "applyTimeTracking": false,
      "image": null,
      "self": "https://environmentname.jiraalign.com/rest/align/api/2/cities/108"
      }
      ]

For each entity, payloads present minor differences, most commonly with attribute keys. Compare the payload of GET Users/{id} :

  • API 1.0:
    • /api/users/28
    • {
      "User": {
      "ID": 28,
      "Email": "user@automation.test",
      "FirstName": "Automation",
      "LastName": "User",
      "Title": "TAQA",
      "UID": "28",
      "RoleID": 9,
      "ExternalID": "",
      "Locked": false,
      "CreateDate": "2018-05-23T13:51:46Z",
      "EnterpirseHierarchy": 15,
      "CostCenterID": 1,
      "RegionID": 5,
      "CityID": 17,
      "HolidayCalendar": 5,
      "TimeTrackRoles": [],
      "EmployeeClassification": 1,
      "StartDate": "2018-05-23T13:51:46Z",
      "UserStartDate": "2018-05-23",
      "IncludeHours": false,
      "IsComplianceManager": false,
      "IsUserManager": false,
      "Company": "",
      "CompanyID": "",
      "EmployeeID": "",
      "IsTimeTracker": false,
      "LastLoginDate": "2023-09-19T23:43:53Z",
      "Notes": "",
      "LastModified": "2020-07-01T15:33:19Z",
      "HolidayCityID": 17,
      "Teams": [
      {
      "TeamId": 5,
      "Name": "NoCapabilitiesHierarchy.Portfolio.Program1 Team",
      "TeamRole": {
      "TeamRoleId": 12,
      "Name": "Team of Team"
      }
      },
      ...
      {
      "TeamId": 1694,
      "Name": "AUT Test Program GPD91NATB5TH0TGBZG Team",
      "TeamRole": {
      "TeamRoleId": 12,
      "Name": "Team of Team"
      }
      }
      ],
      "TimeZoneId": "E. Europe Standard Time",
      "UserTimeTrackingPermissions": {
      "HasTimeEntryPermission": false,
      "HasTimeApprovalPermission": false
      },
      "Avatar": "data:image/png;base64,R0lG...,
      "Self": "https://environmentname.jiraalign.com/api/users/28"
      }
      }
  • API 2.0
    • /rest/align/api/2/users/28
    • {
      "id": 28,
      "uid": "28",
      "firstName": "Automation",
      "lastName": "User",
      "fullName": "Automation User",
      "email": "user@automation.test",
      "userStartDate": "2018-05-23T00:00:00Z",
      "userEndDate": null,
      "isExternal": 0,
      "externalId": null,
      "isLocked": 0,
      "status": "Active",
      "employeeId": "",
      "regionId": 5,
      "title": "TAQA",
      "roleId": 9,
      "cityId": 17,
      "company": null,
      "companyId": null,
      "divisionId": 15,
      "costCenterId": 1,
      "notes": "",
      "timeZone": "E. Europe Standard Time",
      "viewPublicErs": 0,
      "lastLoginDate": "2023-09-19T19:43:53Z",
      "employeeClassification": 1,
      "isTimeTracking": 0,
      "timeTrackingRoles": null,
      "includeHours": 0,
      "holidayRegionId": 5,
      "holidayCityId": 17,
      "isUserManager": 0,
      "managerId": null,
      "timeTrackingStartDate": null,
      "timeApproverId": null,
      "isComplianceManager": 0,
      "createDate": "2018-05-23T09:51:46Z",
      "lastUpdatedDate": null,
      "connectorId": null,
      "userType": null,
      "enterpriseHierarchyId": 15,
      "teams": [
      {
      "teamId": 5,
      "teamName": "NoCapabilitiesHierarchy.Portfolio.Program1 Team",
      "teamType": 2,
      "roleId": 12,
      "roleName": "TeamOfTeam"
      },
      ...
      {
      "teamId": 1694,
      "teamName": "AUT Test Program GPD91NATB5TH0TGBZG Team",
      "teamType": 2,
      "roleId": 12,
      "roleName": "TeamOfTeam"
      }
      ],
      "self": "https://environmentname.jiraalign.com/rest/align/api/2/users/28"
      }

       

Was this article helpful?
0 out of 0 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

Join the Atlassian Community!

The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.

Need to contact Jira Align Support? Please open a support request.