Migrating from 0.5 to 2.0 REST API

Beeswax currently offers two versions of the REST API, the legacy [0.5 version](🔗﻿) and the newly-released 2.0 version. It is our intention to upgrade all 0.5 endpoints to 2.0 and to migrate customers to the new version gradually. As of today, only some endpoints are available in the 2.0 API, so it is reasonable to assume that you will need to work with a combination of the two versions.
While both versions co-exist, it is important to understand the differences between them as well as the migration path for those using some or all of the endpoints of the 0.5 API. 
## Compatibility
The 2.0 API is not backwards compatible with the 0.5 API. We are taking this opportunity to move the API to more standard syntax and to make improvements in the object models. For some Buzz objects, like the new [Targeting](🔗﻿), the new API is quite different and reflects a big upgrade in functionality. As we release more endpoints to the 2.0 API we will attempt to make them hew closely to the 0.5 API to minimize the additional work for developers.
## Paths
The 0.5 API uses the path `/rest/[resource]` while the 2.0 API uses the path `/rest/v2/[resource]`
## Authentication
While we are transitioning from the Buzz 0.5 API to the new Buzz 2.0 API you must authenticate using the [0.5 authentication](🔗﻿). Once you have authenticated, you may make calls to either the 0.5 API or the 2.0 API using the same cookie.
## Object Hierarchy
The basic hierarchy of objects in the Buzz system is not changing with the release of the Buzz 2.0 API. The documentation describing these objects may be found in the 0.5 [documentation hub](🔗﻿).
## API Syntax
The biggest differences between the APIs involve changes to the syntax of requests, responses, and filtering. Each API method has a documentation page that also describes compatibility issues:
﻿[GET-ting Data from the API](🔗﻿) 
﻿[POST-ing to Creating Objects](🔗﻿) 
﻿[PUT-ting Objects with the API](🔗﻿) 
﻿[DELETE-ing Objects with the API](🔗﻿) 
We also newly support `PATCH` and `OPTIONS` methods.
## Bulk Actions
The methods for performing bulk actions have been improved in a number of ways:
We now support bulk object creation using `POST`
Each object has its own dedicated resources for bulk actions. For example, to take a bulk action against `role`, you can access the [/roles/bulk](🔗﻿) resource
Using PATCH, you can either update objects individually (different changes per object) or in the same manner (same changes over many objects) 
## Quick Guide to 0.5 vs 2.0 APIs
ConceptChanges in 2.0 APINotes
AuthenticationNot yet available in 2.0Use the 0.5 authentication resource then interchangeably make requests to resources in either version
PathsInstead of `/rest/[resource]` use

`/rest/v2/[resource]` or
`/rest/v2/ref/[resource]`The 0.5 API does not need to have the version specified.
FilteringNew, powerful filtering syntax. Filtering commands are appended to field names with a double-underscore. For example to filter when an `id` field is great than or equal to 2, add  `id__gte=2` to the GET request.See [GET-ting Data from the API](🔗﻿) for examples.
ViewsViews have been replaced with individual endpoints under the `/ref/` path. The 0.5 API also supported Views as alternative sets of fields under primary resources -- this use case is not supported.See [Reference Resources](🔗﻿).
Multi-AccountFor users enabled with [Multi-Account](🔗﻿) to query across all accounts use the new `all_accounts=true` parameter, rather than `account_id=any`.See [GET-ting Data from the API](🔗﻿).
`GET`Variables should be passed as URL parameters, not http payload.See [GET-ting Data from the API](🔗﻿).
`POST`No change to POST.

Error messages for all operations are improved to include feedback on multiple fields.

Bulk creation now supported.See [POST-ing to Creating Objects](🔗﻿),
`PUT/DELETE`The target resource's `id` field must be included in the URL path rather than in the JSON payload.See [PUT-ting Objects with the API](🔗﻿) and [DELETE-ing Objects with the API](🔗﻿).
`PATCH`New to 2.0

Supports flexible bulk operations.See [PUT-ting Objects with the API](🔗﻿).
`OPTIONS`New to 2.0See [OPTIONs to Understand Resources](🔗﻿) .
TargetingEntirely new resource `targeting-expressions`, replaces `targeting_templates`.See [Targeting](🔗﻿).
ReportingNew, more powerful resources and easier to use API.See [Reporting](🔗﻿).

Concept	Changes in 2.0 API	Notes
Authentication	Not yet available in 2.0	Use the 0.5 authentication resource then interchangeably make requests to resources in either version
Paths	Instead of ``/rest/[resource]`` use ``/rest/v2/[resource]`` or ``/rest/v2/ref/[resource]``	The 0.5 API does not need to have the version specified.
Filtering	New, powerful filtering syntax. Filtering commands are appended to field names with a double-underscore. For example to filter when an ``id`` field is great than or equal to 2, add ``id__gte=2`` to the GET request.	See [GET-ting Data from the API](🔗) for examples.
Views	Views have been replaced with individual endpoints under the ``/ref/`` path. The 0.5 API also supported Views as alternative sets of fields under primary resources -- this use case is not supported.	See [Reference Resources](🔗).
Multi-Account	For users enabled with [Multi-Account](🔗) to query across all accounts use the new ``all_accounts=true`` parameter, rather than ``account_id=any``.	See [GET-ting Data from the API](🔗).
``GET``	Variables should be passed as URL parameters, not http payload.	See [GET-ting Data from the API](🔗).
``POST``	No change to POST. Error messages for all operations are improved to include feedback on multiple fields. Bulk creation now supported.	See [POST-ing to Creating Objects](🔗),
``PUT/DELETE``	The target resource's ``id`` field must be included in the URL path rather than in the JSON payload.	See [PUT-ting Objects with the API](🔗) and [DELETE-ing Objects with the API](🔗).
``PATCH``	New to 2.0 Supports flexible bulk operations.	See [PUT-ting Objects with the API](🔗).
``OPTIONS``	New to 2.0	See [OPTIONs to Understand Resources](🔗) .
Targeting	Entirely new resource ``targeting-expressions``, replaces ``targeting_templates``.	See [Targeting](🔗).
Reporting	New, more powerful resources and easier to use API.	See [Reporting](🔗).