Skip to main content

API Overview

The InForm API provides comprehensive programmatic access to the platform's capabilities, enabling custom integrations, automated workflows, and extended functionality.

API Architecture​

RESTful Design​

The InForm API follows REST principles with:

  • Resource-based URLs: Clear, predictable endpoint structure
  • HTTP Methods: GET, POST, PUT, DELETE for different operations
  • JSON Payloads: Standardized data exchange format
  • HTTP Status Codes: Standard response codes for error handling

Base URL Structure​

https://api.inform.arup.com/v1/

Authentication​

All API requests require authentication via:

  • Azure Active Directory: Enterprise authentication
  • Bearer Tokens: JWT tokens for API access
  • API Keys: Service-to-service authentication (limited scope)

Core API Endpoints​

Authentication & Authorization​

  • Authentication API: Login, token management, permissions
  • User Management: Profile information, team membership
  • Access Control: Project permissions, role-based access

Project Management​

  • Projects API: Create, configure, and manage projects
  • Model Deployment: Upload and configure Grasshopper models
  • Version Control: Manage model versions and deployments

Parametric Exploration​

  • Parameter API: Define and manage design parameters
  • Evaluation API: Execute parametric models with parameter sets
  • Results API: Retrieve geometry, analysis results, and metrics

Analysis & Computation​

  • Analysis API: Integration with computational analysis
  • Performance Metrics: Calculate and retrieve performance data
  • Optimization: Multi-objective optimization and constraint handling

Visualization & UI​

  • Unity Integration API: 3D visualization and interaction
  • Component API: UI components and configuration
  • Visualization Config: Charts, graphs, and data display

Collaboration​

  • Sharing API: Project and variant sharing
  • Comments API: Annotations and feedback
  • Notifications: Real-time updates and alerts

API Reference Structure​

Request Format​

GET /projects/{projectId}/parameters
Authorization: Bearer {token}
Content-Type: application/json

Response Format​

{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "timestamp": "2023-10-15T10:30:00Z",
    "version": "1.0",
    "requestId": "req-123456"
  }
}

Error Format​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter range",
    "details": {
      "parameter": "building_height",
      "value": -10,
      "constraint": "must be positive"
    }
  },
  "metadata": {
    "timestamp": "2023-10-15T10:30:00Z",
    "requestId": "req-123456"
  }
}

Getting Started​

1. Authentication Setup​

// Obtain access token
const response = await fetch('https://api.inform.arup.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'your-client-id',
    client_secret: 'your-client-secret'
  })
});

const { access_token } = await response.json();

2. List Projects​

// Get user projects
const projects = await fetch('https://api.inform.arup.com/v1/projects', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  }
});

const projectList = await projects.json();

3. Execute Model​

// Run parametric model
const result = await fetch(`https://api.inform.arup.com/v1/projects/${projectId}/evaluate`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    parameters: {
      building_height: 50,
      floor_count: 10,
      structural_system: "Steel Frame"
    }
  })
});

const evaluation = await result.json();

SDK and Client Libraries​

JavaScript/TypeScript SDK​

npm install @inform/api-client
import { InformClient } from '@inform/api-client';

const client = new InformClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.inform.arup.com/v1'
});

// Use the client
const projects = await client.projects.list();
const result = await client.models.evaluate(projectId, parameters);

Python SDK​

pip install inform-api-client
from inform_api import InformClient

client = InformClient(
    api_key='your-api-key',
    base_url='https://api.inform.arup.com/v1'
)

# Use the client
projects = client.projects.list()
result = client.models.evaluate(project_id, parameters)

.NET SDK​

dotnet add package Inform.ApiClient
using Inform.ApiClient;

var client = new InformClient(new InformClientOptions
{
    ApiKey = "your-api-key",
    BaseUrl = "https://api.inform.arup.com/v1"
});

// Use the client
var projects = await client.Projects.ListAsync();
var result = await client.Models.EvaluateAsync(projectId, parameters);

Rate Limiting and Quotas​

Rate Limits​

  • Standard API: 1000 requests per hour per user
  • Model Evaluation: 100 evaluations per hour per project
  • Bulk Operations: 10 concurrent operations

Quota Management​

  • Monthly Limits: Based on subscription tier
  • Compute Usage: Charged by execution time
  • Storage Limits: Project and model storage quotas

Headers​

Response headers include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1634567890
X-RateLimit-Retry-After: 3600

Error Handling​

HTTP Status Codes​

  • 200 OK: Successful request
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Authentication required or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource does not exist
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

Error Categories​

  • Validation Errors: Invalid input data or parameters
  • Authentication Errors: Login or permission issues
  • Resource Errors: Missing or inaccessible resources
  • Rate Limit Errors: Too many requests
  • Server Errors: Internal platform issues

Error Response Example​

{
  "success": false,
  "error": {
    "code": "PARAMETER_OUT_OF_RANGE",
    "message": "Parameter value exceeds allowed range",
    "details": {
      "parameter": "building_height",
      "value": 500,
      "min": 10,
      "max": 200
    },
    "documentation_url": "https://docs.inform.arup.com/api/errors#PARAMETER_OUT_OF_RANGE"
  }
}

Webhooks and Real-Time Updates​

Webhook Configuration​

Subscribe to events for real-time updates:

// Configure webhook endpoint
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks/inform',
  events: ['model.evaluation.completed', 'project.shared'],
  secret: 'your-webhook-secret'
});

Event Types​

  • Model Events: Evaluation completed, deployment status
  • Project Events: Created, shared, permission changes
  • User Events: Login, project access
  • System Events: Maintenance, service updates

WebSocket Connections​

For real-time collaboration:

const socket = new WebSocket('wss://api.inform.arup.com/v1/ws');

socket.onmessage = (event) => {
  const message = JSON.parse(event.data);
  // Handle real-time updates
};

API Versioning​

Version Strategy​

  • URL Versioning: /v1/, /v2/ in the URL path
  • Backward Compatibility: Previous versions supported for 12 months
  • Deprecation Notice: 6-month advance notice for breaking changes

Current Versions​

  • v1: Current stable version
  • v2: Beta version with new features
  • v0: Legacy version (deprecated)

Migration Guide​

When new versions are released:

  1. Review changelog for breaking changes
  2. Test in development environment
  3. Update client code incrementally
  4. Monitor for issues after deployment

Performance and Optimization​

Caching​

  • GET Requests: Cached for 5 minutes by default
  • ETags: Use conditional requests for efficiency
  • Cache-Control: Respect cache headers

Pagination​

Large datasets use cursor-based pagination:

// Get first page
const response = await client.projects.list({ limit: 50 });

// Get next page
const nextPage = await client.projects.list({ 
  limit: 50, 
  cursor: response.metadata.next_cursor 
});

Batch Operations​

Reduce API calls with batch requests:

// Batch parameter evaluation
const results = await client.models.batchEvaluate(projectId, [
  { building_height: 30, floor_count: 6 },
  { building_height: 40, floor_count: 8 },
  { building_height: 50, floor_count: 10 }
]);

Security Best Practices​

API Key Management​

  • Secure Storage: Never commit API keys to version control
  • Environment Variables: Use environment-specific configuration
  • Key Rotation: Regularly rotate API keys
  • Scope Limitation: Use minimal required permissions

Request Security​

  • HTTPS Only: All API requests must use HTTPS
  • Input Validation: Validate all input parameters
  • Rate Limiting: Implement client-side rate limiting
  • Error Handling: Don't expose sensitive information in errors

Data Protection​

  • Data Encryption: All data encrypted in transit and at rest
  • Access Logging: All API access is logged and monitored
  • Compliance: GDPR, SOC2, and industry-specific compliance
  • Data Retention: Automatic data lifecycle management

Next Steps​

Detailed API Documentation​

Development Resources​

Support and Community​

  • API Forum: Developer community and discussions
  • Support Portal: Technical support and bug reports
  • Changelog: API updates and version history
  • Status Page: Real-time API status and uptime