API Deprecations

Overview

As the Netilion API evolves, certain endpoints and features may be deprecated to improve the API design and maintainability. Deprecated endpoints in API v1 will be removed or significantly changed in API v2 with breaking changes.

This document outlines all currently deprecated endpoints in v1 and provides guidance on how to migrate to the v2 equivalents.

Deprecation Timeline

• Deprecated Since: Indicates when the endpoint was marked as deprecated
• Target Removal: The date or API version when the deprecated endpoint will be removed
• Migration Path: Recommended approach to update your integration

Note

Always monitor this page for updates. We recommend proactively migrating to v2 endpoints before they become mandatory.

Display labels

Status

• Deprecated Since: released February 2025
• Sunset Date: March 1, 2027
• Reason: The old payload structure only supported flat key-value pairs and couldn’t accommodate the new parameters (“preferred_unit”, “unit_extension”, “precision”, “priority”, “is_visible”, “expected_min”, “expected_max”, and “is_primary”). The new v2 structure uses nested objects for each parameter, enabling better extensibility and support for additional metadata.

v1 Endpoint

PATCH /v1/assets/{asset_id}/display_labels
PATCH /v1/instrumentations/{instrumentation_id}/display_labels

v2 Alternative

PATCH /v2/assets/{asset_id}/display_labels
PATCH /v2/instrumentations/{instrumentation_id}/display_labels

Migration Guide

Key Changes:

• Payload structure changed from flat key-value pairs to nested objects with detailed configuration for each parameter
• Each display label now supports additional metadata: preferred_unit, unit_extension, precision, priority, is_visible, expected_min, expected_max, and is_primary
• Request/response format now uses objects instead of strings for label values, enabling richer label configuration
• All new parameters are included in both PATCH requests and API responses

Example: Patching Display Labels (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/assets/{asset_id}/display_labels', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "temperature": "Temperature",
    "pressure": "Pressure"
  })
})

Example: Patching Display Labels (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/assets/{asset_id}/display_labels', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "temperature": {
      "name": "Temperature",
      "preferred_unit": "°C",
      "unit_extension": "Celsius",
      "precision": 2,
      "priority": 1,
      "is_visible": true,
      "expected_min": -50,
      "expected_max": 150,
      "is_primary": true
    },
    "pressure": {
      "name": "Pressure",
      "preferred_unit": "bar",
      "unit_extension": "Barometric",
      "precision": 3,
      "priority": 2,
      "is_visible": true,
      "expected_min": 0,
      "expected_max": 100,
      "is_primary": false
    }
  })
})

For complete v2 API documentation, see the Netilion API.

Permissions and Owner

Status

• Deprecated Since: May 1, 2025
• Sunset Date: May 1, 2027
• Reason: The v1 endpoint used predictable sequential IDs that could be enumerated or iterated through, creating a security vulnerability. By transitioning to email-based identification for User assignables, we eliminate this security risk while also improving usability. Additionally, v2 introduces array-based permission_types for bulk permission operations and adds PATCH support for updating existing permissions, streamlining the API and reducing unnecessary API calls.

v1 Endpoints

Permissions Management

GET    /v1/permissions
POST   /v1/permissions
GET    /v1/permissions/{id}
DELETE /v1/permissions/{id}

Owner Management

POST   /v1/owners
DELETE /v1/owners

v2 Alternatives

Permissions Management

GET    /v2/permissions
POST   /v2/permissions
GET    /v2/permissions/{id}
PATCH  /v2/permissions/{id}  # NEW in v2
DELETE /v2/permissions/{id}

Owner Management

POST   /v2/owners
DELETE /v2/owners

Migration Guide

Key Changes for Permissions

1. Permission types format changed: permission_type (string) → permission_types (array)
2. Bulk permission creation: Multiple permission types can be created in a single request
3. Assignable identification: User assignables can now be identified by email in addition to ID
4. Update capability: New PATCH endpoint allows updating existing permissions
5. Response structure: Permissions now returned with permission_types array instead of individual records per type

Key Changes for Owners

1. User identification: Changed from assignable.id (integer) → assignable.email (string)
2. Simplified workflow: Email-based identification is more intuitive and doesn’t require knowing user IDs

Example 1: Creating Permissions

v1 - DEPRECATED (single permission type):

fetch('https://api.netilion.endress.com/v1/permissions', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "permission_type": "can_read, can_update",
    "assignable": {
      "id": 123,
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

v2 - RECOMMENDED (multiple permission types):

fetch('https://api.netilion.endress.com/v2/permissions', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "permission_types": ["can_read", "can_update"],  // Array instead of single string
    "assignable": {
      "email": "user@example.com",  // Email for User type
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

Note: For Usergroup assignables, continue using id in v2:

{
  "permission_types": ["can_read", "can_update"],
  "assignable": {
    "id": 789,  // ID for Usergroup type
    "type": "Usergroup"
  },
  "permitable": {
    "id": 456,
    "type": "Asset"
  }
}

Example 2: Adding/Removing Owners

v1 - DEPRECATED (using user ID):

// Add owner
fetch('https://api.netilion.endress.com/v1/owners', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "assignable": {
      "id": 123,  // User ID required
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

// Remove owner
fetch('https://api.netilion.endress.com/v1/owners', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "assignable": {
      "id": 123,
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

v2 - RECOMMENDED (using email):

// Add owner
fetch('https://api.netilion.endress.com/v2/owners', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "assignable": {
      "email": "user@example.com",  // Email instead of ID
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

// Remove owner
fetch('https://api.netilion.endress.com/v2/owners', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "assignable": {
      "email": "user@example.com",
      "type": "User"
    },
    "permitable": {
      "id": 456,
      "type": "Asset"
    }
  })
})

Example 3: Getting Permissions

v1 - DEPRECATED:

fetch('https://api.netilion.endress.com/v1/permissions?permitable_id=456&permitable_type=Asset', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

// Response: Separate permission object for each type with artificial ID generated from real object ID
// The artificial IDs are constructed by adding an offset to the base object ID:
// - Base ID 123456 + 1 = 1234561 (can_read)
// - Base ID 123456 + 2 = 1234562 (can_update)
// - Base ID 123456 + 4 = 1234564 (can_delete)
// {
//   "permissions": [
//     { "id": "1234561", "permission_type": "can_read", ... },
//     { "id": "1234562", "permission_type": "can_update", ... },
//     { "id": "1234564", "permission_type": "can_delete", ... }
//   ]
// }

v2 - RECOMMENDED:

fetch('https://api.netilion.endress.com/v2/permissions?permitable_id=456&permitable_type=Asset', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

// Response: Single permission object with types array
// {
//   "permissions": [
//     { "id": 123456, "permission_types": ["can_read", "can_update"], ... }
//   ]
// }

Example 4: Updating Permissions (NEW in v2)

v2 ONLY - Not available in v1:

fetch('https://api.netilion.endress.com/v2/permissions/123456', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "permission_types": ["can_read", "can_update", "can_delete"]  // Update permission types
  })
})

Example 5: Deleting Permissions

v1 - DEPRECATED (ID includes permission type):

// Delete specific permission type (note: ID format includes type indicator)
fetch('https://api.netilion.endress.com/v1/permissions/1234561', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

// Delete all permission types with ?all=true parameter
fetch('https://api.netilion.endress.com/v1/permissions/1234561?all=true', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

v2 - RECOMMENDED (standard ID format):

// Delete permission (removes all permission types for this assignable-permitable pair)
fetch('https://api.netilion.endress.com/v2/permissions/123456', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

For complete v2 API documentation, see the Netilion API.

Tenants

Status

• Deprecated Since: July 1, 2025
• Sunset Date: July 1, 2027
• Reason: Tenant membership management in v1 uses predictable sequential user IDs that can be enumerated or iterated through, creating a security vulnerability. By transitioning to email-based identification in v2, we eliminate this security risk while also removing the need for extra lookups and aligning tenant membership workflows with other v2 identity patterns.

v1 Endpoints (DEPRECATED)

Admin Membership

POST   /v1/tenants/{tenant_id}/admins
PATCH  /v1/tenants/{tenant_id}/admins
DELETE /v1/tenants/{tenant_id}/admins

User Membership

POST   /v1/tenants/{tenant_id}/users
PATCH  /v1/tenants/{tenant_id}/users
DELETE /v1/tenants/{tenant_id}/users

v2 Alternatives

Admin Membership

POST   /v2/tenants/{tenant_id}/admins
PATCH  /v2/tenants/{tenant_id}/admins
DELETE /v2/tenants/{tenant_id}/admins

User Membership

POST   /v2/tenants/{tenant_id}/users
PATCH  /v2/tenants/{tenant_id}/users
DELETE /v2/tenants/{tenant_id}/users

Migration Guide

Key Changes:

• Request body changed from user IDs to user emails
• v2 payloads use users or admins arrays of { "email": "..." } objects
• Endpoint paths are unchanged but moved under /v2

Example: Add Admins to Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/admins', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "admins": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Add Admins to Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/admins', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "admin.one@example.com" },
      { "email": "admin.two@example.com" }
    ]
  })
})

Example: Replace Admins of Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/admins', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "admins": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Replace Admins of Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/admins', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "admin.one@example.com" },
      { "email": "admin.two@example.com" }
    ]
  })
})

Example: Remove Admins from Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/admins', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "admins": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Remove Admins from Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/admins', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "admin.one@example.com" },
      { "email": "admin.two@example.com" }
    ]
  })
})

Example: Add Users to Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/users', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Add Users to Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/users', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

Example: Replace Users of Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/users', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Replace Users of Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/users', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

Example: Remove Users from Tenant (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/tenants/{tenant_id}/users', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Remove Users from Tenant (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/tenants/{tenant_id}/users', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

For complete v2 API documentation, see the Netilion API.

User roles

Status

• Deprecated Since: July 1, 2025
• Sunset Date: July 1, 2027
• Reason: User role membership management in v1 uses predictable sequential user IDs that can be enumerated or iterated through, creating a security vulnerability. By transitioning to email-based identification in v2, we eliminate this security risk while also simplifying workflows, improving readability, and matching other v2 identity patterns.

v1 Endpoints (DEPRECATED)

POST   /v1/userroles/{userrole_id}/users
PATCH  /v1/userroles/{userrole_id}/users
DELETE /v1/userroles/{userrole_id}/users

v2 Alternatives

POST   /v2/userroles/{userrole_id}/users
PATCH  /v2/userroles/{userrole_id}/users
DELETE /v2/userroles/{userrole_id}/users

Migration Guide

Key Changes:

• Request body changed from user IDs to user emails
• Payload schema in v2 expects users as objects with email
• Endpoint paths are the same, but under the /v2 namespace

Example: Add Users to User Role (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/userroles/{userrole_id}/users', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Add Users to User Role (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/userroles/{userrole_id}/users', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

Example: Replace Users of User Role (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/userroles/{userrole_id}/users', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Replace Users of User Role (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/userroles/{userrole_id}/users', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

Example: Remove Users from User Role (v1 - DEPRECATED)

fetch('https://api.netilion.endress.com/v1/userroles/{userrole_id}/users', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "id": 123 },
      { "id": 456 }
    ]
  })
})

Example: Remove Users from User Role (v2 - RECOMMENDED)

fetch('https://api.netilion.endress.com/v2/userroles/{userrole_id}/users', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "users": [
      { "email": "user.one@example.com" },
      { "email": "user.two@example.com" }
    ]
  })
})

For complete v2 API documentation, see the Netilion API.

Need Help?

If you have questions about deprecations or need migration assistance:

• Review the API Versioning policy
• Check the API Documentation for detailed endpoint specifications
• See Code Examples for implementation patterns
• Contact our support team via the Netilion portal