Guide to v3-to-v4 APIs Migration (v3 APIs are deprecated)
Equinix Fabric v4 API brings a number of enahncements:
- New data model entities: Fabric Cloud Router, connection routing protocols
- Insight into port and connection bandwidth utilization statistics
- Consolidated seller and buyer endpoints for improved developer experience
- Enhancements in existing data model entities enabling more refined integration
- Bulk creation and modification of selected entities
v3 to v4 APIs mapping
Connections
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Create connection | POST /ecx/v3/l2/connections | POST /fabric/v4/connections | Request: - Response: v4 API reqest response includes the entire connection object, while the v3 API request returns only a request status message. |
| Create multiple connections | - | POST /fabric/v4/connections | You can create multiple connections to Enterprises, AWS, Microsoft, and others. Just create a primary connection first. You can set the priority field as "PRIMARY" but don't pass a group (unique Id) in the redundancy object. In the response, you will get a unique Id (the "group" field in the redundancy object). When creating the secondary connection, set the priority as "SECONDARY." Also, set the group field of the redundancy object equal to the group field you received in the response of the primary connection. |
| Get all connections | GET /ecx/v3/l2/seller/connections GET /ecx/v3/l2/buyer/connections | POST /fabric/v4/connections/search | Request: v3 and v4 use different HTTP methods. v4 APIs provides a single endpoint for seller and buyer connections. To retrieve all connections, use the POST /fabric/v4/connections/search request with empty filter body parameter. Response: v3 and v4 connection objects have different structure and parameters' names. |
| Get specified connection | GET /ecx/v3/l2/connections/{uuid} | GET /fabric/v4/connections/{uuid} | Request: - Response: v3 and v4 connection objects have different structure and parameters' names. |
| Validate connection authorization key | GET /ecx/v3/l2/connections/validateAuthorizationKey | POST /fabric/v4/connection/validate | Request: v3 and v4 use different HTTP methods. In v3 the value of the authorization key is provided as a query parameter while in the v4 it's specified in the request body. Response: The response payload is different due to changes in the connection object. |
| Delete connection | DELETE /ecx/v3/l2/connections/{uuid} | DELETE /fabric/v4/connections{uuid} | Request: - Response: v4 request returns the entire object in the response, v3 returns just a request status message. |
| Update connection | PATCH /ecx/v3/l2/connections/{uuid} | PATCH /fabric/v4/connections/{uuid} | Request: v3 and v4 have different request body. Response: v4 API reqest response includes the entire connection object, while the v3 API request returns only a request status message. |
Metros
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Get metros | GET /ecx/v3/l2/common/metros | GET /fabric/v4/metros | Request: - Response: v4 response includes more details such as average latency to all connected metros. |
| Get all subscriber metros | - | GET /fabric/v4/metros?presence=MY_PORTS | Returns metros in which you are present. |
| Get specified metro | - | GET /fabric/v4/metros/{uuid} | Returns the details on a specified metro. |
Ports
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Get all ports | GET /ecx/v3/port/userport | GET /fabric/v4/ports | Request: - Response: v3 and v4 port objects have different structure and parameters' names. |
| Get specified port | - | GET /fabric/v4/ports/{portUuid} | Returns details of a specified port. |
Pricing
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Retrieve pricing | GET /ecx/v3/l2/connections/prices | POST /fabric/v4/prices/search | Request: v3 and v4 use different HTTP methods. In the v3 the connection parameters values are provided as a query parameter while in the v4 they are specified in the request body. V4 API enables retrieving pricing information not only for connections but also for ports, IP blocks and Fabric Cloud Routers. Response: v3 and v4 responses are different due to changes in the existing data model entities and introduction of new ones. |
Fabric Cloud Routers
Fabric Cloud Routers enable connecting to any Enterprise Private Cloud, Cloud Service Providers or any Equinix hosted services using Equinix Fabric infrastructure, without physical presence on Platform Equinix.
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Create Fabric Cloud Router | - | POST /fabric/v4/routers/{uuid} | Creates a Fabric Cloud Router instance. |
| Update Fabric Cloud Router | - | PATCH /fabric/v4/routers/{uuid} | Modifies a Fabric Cloud Router instance. |
| Get Specified Fabric Cloud Router | - | GET /fabric/v4/routers/{uuid} | Returns details of a specified Fabric Cloud Router instance. |
| Delete Fabric Cloud Router | - | DELETE /fabric/v4/routers/{uuid} | Deletes a Fabric Cloud Router instance. |
| Retrieve Fabric Cloud Routers | - | POST /fabric/v4/routers/search | Retrieves Fabric Cloud Router instances that match provided search criteria. |
| Get All Fabric Cloud Router Packages | - | GET /fabric/v4/routerPackages | Retrieves Fabric Cloud Router package details. |
| Get Specified Fabric Cloud Router Pakage | - | GET /fabric/v4/routerPackages/{routerPackageCode} | Retrieves details of a specified Fabric Cloud Router package. |
Metrics
These endpoints provide insight into bandwidth utilization allowing you to plan and manage the capacity of your access points to ensure optimal service delivery.
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Get Specified Port Statistics | GET /ecx/v3/stats/port/{uuid} | GET /fabric/v4/ports/{uuid}/stats | Provides service-level traffic metrics so that you can gather key information required to manage service subscription sizing and bandwidth. |
| Get Ports Statistics | - | GET /fabric/v4/ports/stats | Retrieves traffic data for the most efficient Equinix Fabric™ ports in the specified metro. |
| Get Connection Statistics | - | GET /fabric/v4/connections/{uuid}/stats | Provides service-level traffic metrics so that you can gather key information required to manage service subscription sizing and capacity. |
Routing protocols
Routing protocols instances define routing between connection endpoints.
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Get All Routing Protocol Instances | - | GET /fabric/v4/connections/{connectionUuid}/routingProtocols | Retrieves routing protocol definitions associated with a specified connection. |
| Get Specified Routing Protocol Instance | - | GET /fabric/v4/connections/{connectionUuid}/routingProtocols/{routingProtocolUuid} | Retrieves details of a specified routing protocol definition associated with a given connection. |
| Create Routing Protocol Instances | - | POST /fabric/v4/connections/{connectionUuid}/routingProtocols/bulk | Adds routing protocol definitions to a given connection. |
| Delete Routing Protocol Instance | - | DELETE /fabric/v4/connections/{connectionUuid}/routingProtocols/{routingProtocolUuid} | Deletes a specified routing protocol definition associated with a given connection. |
Service profiles
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Create Service Profile (Seller) | POST /ecx/v3/l2/serviceprofiles | POST /fabric/v4/serviceProfiles | Request: The v3 and the v4 service profile objects have different structure and parameters' names. |
| Get Service Profiles (Buyer) | GET /ecx/v3/l2/serviceprofiles/services | GET /fabric/v4/serviceProfiles | Request: The v3 API uses a dedicated endpoint to list service profiles for subscribers while the v4 API introduces the viewPoint parameter that specifies the data set relevant to subscribers. The v4 API requires the ic-version header parameter. Response: The v3 and the v4 service profile objects have different structure and parameters' names |
| Get Service Profiles (Seller) | GET /ecx/v3/l2/serviceprofiles | GET /fabric/v4/serviceProfiles | Request: The v3 API uses a dedicated endpoint to list service profiles for service providers while the v4 API introduces the viewPoint parameter that specifies the data set relevant to subscribers. The v4 API requires the ic-version header parameter. Response: The v3 and the v4 service profile objects have different structure and parameters' names. |
| Get Specified Service Profile (Buyer) | GET /ecx/v3/l2/serviceprofiles/services/{uuid} | GET /fabric/v4/serviceProfiles/{uuid} | Request: The v3 API uses a dedicated endpoint to return a service profile details relevant for subscribers while the v4 API introduces the viewPoint parameter that specifies the relevant data set. The v4 API requires the ic-version header parameter. Response: The v3 and the v4 service profile objects have different structure and parameters' names. |
| Get Specified Service Profile (Seller) | GET /ecx/v3/l2/serviceprofiles/{uuid} | GET /fabric/v4/serviceProfiles/{uuid} | Request: The v3 API uses a dedicated endpoint to return a service profile details relevant to service providers while the v4 API introduces the viewPoint parameter that specifies the relevant data set. The v4 API requires the ic-version header parameter. Response: The v3 and the v4 service profile objects have different structure and parameters' names |
| Get Service Profile Validation {integrationId} | GET /ecx/v3/l2/serviceprofiles/validateIntegrationId/{integrationId} | - | Validates a layer 2 API integration ID and returns associated regions. |
| Replace Service Profile (Seller) | PUT /ecx/v3/l2/serviceprofiles/{uuid} | PUT /fabric/v4/serviceProfiles/{uuid} | Request: The v3 and the v4 service profile objects have different structure and parameters' names. Response: v4 API reqest response includes the entire service profile object, while the v3 API request returns only the uuid. |
| Update Service Profile | - | PATCH /fabric/v4/serviceProfiles/{uuid} | Updates selected service profile parameters. |
| Delete Service Profile {uuid} (Seller) | DELETE /ecx/v3/l2/serviceprofiles/services/{uuid} | DELETE /fabric/v4/serviceProfiles/{uuid} | Request: - Response: v4 API reqest response includes the entire service profile object, while the v3 API request returns only the status message. |
Service tokens
Service tokens authorize third-parties to connect to your services.
| Data model feature | v3 API request | v4 API request | Description |
|---|---|---|---|
| Create a service tokens | POST /ecx/v3/serviceTokens | POST /fabric/v4/serviceTokens | Generates a service token. |
| Get All Service Tokens | GET /ecx/v3/serviceTokens | GET /fabric/v4/serviceTokens | Retrieves details of all service tokens associated with the specified account credentials. |
| Get Specified Service Tokens | GET /ecx/v3/serviceTokens/{uuid} | GET /fabric/v4/serviceTokens/{uuid} | Retrieves details of a specified service token. |
| Delete Specified Service Tokens | DELETE /ecx/v3/serviceTokens/{uuid} | DELETE /fabric/v4/serviceTokens | Deletes a specified service token. |