Skip to content

Latest commit

 

History

History
380 lines (277 loc) · 8.98 KB

API_v1.md

File metadata and controls

380 lines (277 loc) · 8.98 KB
Raw

Freerouting API Documentation

The Freerouting API provides auto-routing functionality through standard HTTP RESTful endpoints.

You can test the GET endpoints directly in your browser, but we highly recommend using tools like Postman or Swagger UI for more extensive testing.

Base URL

The base URL for the API is:

{{root_url}}/{{version}}

Where {{root_url}} is your server's address and {{version}} refers to the API version (v1, v2, etc.).

Example Base URL

https://api.freerouting.app/v1

Typical User Workflow

  1. (optional) Register at www.freerouting.app and get an API key.
  2. (optional) Include the API key in your requests under the Authorization header.
  3. Check if you can reach the API by calling the service status endpoint.
  4. Create a session to start a new routing job.
  5. Enqueue a new routing job with the desired settings.
  6. (optional) Change the default settings.
  7. Submit the input for the job.
  8. Start the job.
  9. (optional) Get progress reports of the job.
  10. Retrieve the output of the job when it is completed.

Authentication

Some endpoints require authentication via a API Key. To get a API key, register at www.freerouting.app and include it in your requests under the Authorization header:

Authorization: Bearer <API_KEY>

Endpoints

Service Status

  • Get Service Status

    GET /system/status

    Description: Returns the current status of the system.

    Response body:

    {
  "status": "OK",
  "cpu_load": 5.234029795633588,
  "ram_used": 101,
  "ram_available": 130,
  "storage_available": 229,
  "session_count": 2
}

  • Get Environment Information

    GET /system/environment

    Description: Returns information about the system environment.

Sessions

  • Create a Session

    POST /sessions/create

    Description: Creates a new session.

    Response body: Contains the new session ID.

    {
  "id": "13f4f1b4-29a1-48a5-8efb-8cec519d8bd3",
  "user_id": "d0071163-7ba3-46b3-b3af-bc2ebfd4d1a0",
  "host": "Postman/11.14"
}

  • List All Sessions

    GET /sessions/list

    Description: Retrieves a list of all active sessions.

  • Retrieve a Specific Session

    GET /sessions/{sessionId}

    Parameters:

    • sessionId (required): The unique identifier of the session.

    Description: Retrieves detailed information about a specific session.

  • Get log entries of a session

    GET /sessions/{sessionId}/logs/{timestamp}

    Parameters:

    • sessionId (required): The unique identifier of the session.
    • 'timestamp' (optional): The timestamp from which the log entries will be listed.'

    Description: Retrieves a JSON array of log entries for a specific session.

Routing Jobs

  • Enqueue a Job

    POST /jobs/enqueue

    Request body: Contains the session ID and the name of the job.

    {  
  "session_id": "2703e30e-e891-422d-ad4e-efefd6d4a3ce",
  "name": "BBD-Mars-64-revE",
  "priority": "NORMAL"
}

    Description: Submits a new routing job to be processed.

  • List Jobs for a Session

    GET /jobs/list/{sessionId}

    Parameters:

    • sessionId (required): The unique identifier of the session.

    Description: Retrieves a list of routing jobs associated with a specific session.

  • Update Job Settings

    POST /jobs/{jobId}/settings

    Request body: Contains the desired new settings.

    {
  "max_passes": 5,
  "via_costs": 42
}

    Parameters:

    • jobId (required): The unique identifier of the job.

    Description: Updates the settings for a specific routing job.

  • Start a Job

    PUT /jobs/{jobId}/start

    Parameters:

    • jobId (required): The unique identifier of the job.

    Description: Starts processing the specified routing job.

  • Get log entries of a job

    GET /jobs/{jobId}/logs/{timestamp}

    Parameters:

    • JobId (required): The unique identifier of the job.
    • 'timestamp' (optional): The timestamp from which the log entries will be listed.'

    Description: Retrieves a JSON array of log entries for a specific job.

Inputs and Outputs

  • Submit Input for a Job

    POST /jobs/{jobId}/input

    Parameters:

    • JobId (required): The unique identifier of the job.
    • filename (required): The name of the file.
    • data (required): The base-64 encoded data of the file.

    Description: Submits input data for a routing job.

    Request body: Contains the filename and the Base64-encoded Specctra DSN data.

    {
  "filename": "BBD-Mars-64-revE.dsn",
  "data": "KGFyZHdhcmVcU...W1hdGY5OC4zMTcgLKQ0K"
}

  • Get Output for a Job

    GET /jobs/{jobId}/output

    Parameters:

    • jobId (required): The unique identifier of the job.

    Description: Retrieves the output data for a completed routing job.

    Response body: Contains some details and the Base64-encoded Specctra SES data.

    {
  "job_id": "a4155510-4db2-412d-ad58-70b7c58c031d",
  "data": "KHNlc3Npb24gI...QogICAgKQogICkKKQ==",
  "size": 13150,
  "crc32": 264089660,
  "format": "SES",
  "statistics": {
      "host": null,
      "layer_count": 2,
      "component_count": 15,
      "netclass_count": null,
      "total_net_count": null,
      "unrouted_net_count": 75,
      "routed_net_count": 267,
      "routed_net_length": null,
      "clearance_violation_count": null,
      "via_count": 133
  },
  "filename": "BBD-Mars-64-revE.ses",
  "path": ""
}

Progress Reports

  • Get Progress Report for a Job

    GET /jobs/{jobId}

    Parameters:

    • jobId (required): The unique identifier of the job.

    Description: Retrieves the current progress of a routing job.

    Response body: Contains the details of the job.

    {
  "id": "a4155510-4db2-412d-ad58-70b7c58c031d",
  "created_at": "2024-10-22T08:28:59.106759042Z",
  "started_at": "2024-10-22T08:29:47.985542527Z",
  "input": {
      "size": 50853,
      "crc32": 4085067588,
      "format": "DSN",
      "statistics": {
          "host": "KiCad's Pcbnew,(5.1.5)-3",
          "layer_count": 2,
          "component_count": 16,
          "netclass_count": 1,
          "total_net_count": 160,
          "unrouted_net_count": null,
          "routed_net_count": 0,
          "routed_net_length": null,
          "clearance_violation_count": null,
          "via_count": 66
      },
      "filename": "BBD-Mars-64-revE.dsn",
      "path": ""
  },
  "session_id": "2703e30e-e891-422d-ad4e-efefd6d4a3ce",
  "name": "BBD-Mars-64-revE",
  "state": "RUNNING",
  "priority": "NORMAL",
  "stage": "ROUTING",
  "router_settings": {
      "default_preferred_direction_trace_cost": 1.0,
      "default_undesired_direction_trace_cost": 1.0,
      "max_passes": 100,
      "fanout_max_passes": 20,
      "max_threads": 1,
      "improvement_threshold": 0.01,
      "trace_pull_tight_accuracy": 500,
      "allowed_via_types": true,
      "via_costs": 42,
      "plane_via_costs": 5,
      "start_ripup_costs": 100,
      "automatic_neckdown": true
  }
}

Notes

  • Make sure to replace {{base_url}} with the actual API base URL and {{version}} with the version you're using.
  • Endpoints that include parameters like {sessionId} or {jobId} need to be replaced with actual values.

Developer Use Case: {{version}} = "dev"

For developers, the Freerouting API offers a special "dev" version designed for testing and development purposes. In this case, the endpoints do not require authentication, and they return structurally correct, mocked data to facilitate integration and testing.

Key Features

  • No Authentication Required: All endpoints in the "dev" version can be accessed without needing a Personal Access Token.
  • Mocked Data: The API responses provide realistic, but mocked data that is structurally correct to simulate real-world API interactions.

Example

To get the service status in the "dev" environment:

GET https://api.freerouting.app/dev/system/status

Response (mocked data)

{
  "status": "OK",
  "cpu_load": 62.73316938805016,
  "ram_used": 67,
  "ram_available": 32,
  "storage_available": 1706,
  "session_count": 1
}

The "dev" version is useful for testing the API integration without relying on live data or requiring authentication.