GenNet

GenNet API Documentation

Overview

The GenNet API provides RESTful and GraphQL interfaces for managing Gene Regulatory Networks, executing analysis workflows, and accessing collaborative features. All APIs follow REST principles and return JSON responses.

🔐 Authentication

All API requests require authentication via JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Obtaining a Token

curl -X POST https://api.gennet.cloud/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

🌐 API Endpoints

Base URL

https://api.gennet.cloud/api/v1

Networks API

List Networks

GET /networks

Parameters:

• page (integer, optional): Page number (default: 1)
• limit (integer, optional): Items per page (default: 20)
• search (string, optional): Search query

Response:

{
  "networks": [
    {
      "id": "net-123",
      "name": "Sample GRN",
      "description": "Example network",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "node_count": 50,
      "edge_count": 120
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

Create Network

POST /networks

Request Body:

{
  "name": "New GRN",
  "description": "Description of the network",
  "nodes": [
    {
      "id": "gene1",
      "type": "gene",
      "properties": {
        "expression": 0.5,
        "symbol": "GENE1"
      }
    }
  ],
  "edges": [
    {
      "source": "gene1",
      "target": "gene2",
      "weight": 0.8,
      "type": "activation"
    }
  ]
}

Get Network

GET /networks/{id}

Update Network

PUT /networks/{id}

Delete Network

DELETE /networks/{id}

Workflows API

List Workflows

GET /workflows

Create Workflow

POST /workflows

Request Body:

{
  "name": "Qualitative Analysis",
  "workflow_type": "qualitative",
  "network_id": "net-123",
  "parameters": {
    "ctl_formula": "AG(g1 > 0.5)",
    "k_parameter_range": [1, 10],
    "max_states": 1000
  }
}

Workflow Types:

• qualitative: CTL verification and state graph analysis
• hybrid: Time delay computation
• ml: Machine learning inference and prediction

Get Workflow Status

GET /workflows/{id}/status

Response:

{
  "id": "wf-456",
  "state": "running",
  "progress": 65,
  "current_step": "Parameter optimization",
  "estimated_completion": "2024-01-15T11:00:00Z",
  "errors": []
}

Get Workflow Results

GET /workflows/{id}/results

Users API

Get Current User

GET /users/me

Update Profile

PUT /users/me

Collaboration API

Join Workspace

POST /workspaces/{id}/join

Get Workspace Members

GET /workspaces/{id}/members

📊 GraphQL API

GraphQL endpoint available at /graphql with full introspection.

Schema Highlights

type Query {
  networks(search: String, limit: Int): [Network!]!
  network(id: ID!): Network
  workflows(networkId: ID): [Workflow!]!
  workflow(id: ID!): Workflow
  user(id: ID!): User
}

type Mutation {
  createNetwork(input: CreateNetworkInput!): Network!
  updateNetwork(id: ID!, input: UpdateNetworkInput!): Network!
  deleteNetwork(id: ID!): Boolean!
  
  createWorkflow(input: CreateWorkflowInput!): Workflow!
  cancelWorkflow(id: ID!): Boolean!
}

type Subscription {
  networkUpdated(networkId: ID!): Network!
  workflowStatusChanged(workflowId: ID!): WorkflowStatus!
}

Example Query

query GetNetworkWithWorkflows {
  network(id: "net-123") {
    id
    name
    nodes {
      id
      type
      properties
    }
    edges {
      source
      target
      weight
    }
    workflows {
      id
      name
      state
      results {
        type
        data
      }
    }
  }
}

🔄 Real-time Updates

The API supports WebSocket connections for real-time updates:

const ws = new WebSocket('wss://api.gennet.cloud/ws?token=<jwt-token>');

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Real-time update:', update);
};

📋 Error Handling

All APIs return standard HTTP status codes:

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 422: Validation Error
• 500: Internal Server Error

Error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid network data",
    "details": {
      "field": "nodes",
      "issue": "Missing required properties"
    }
  }
}

📊 Rate Limiting

• Authenticated requests: 1000 per hour
• Anonymous requests: 100 per hour
• Rate limit headers included in responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

🧪 Testing with Postman

Import API.postman_collection.json into Postman for interactive testing. The collection includes:

• Authentication flows
• Sample requests for all endpoints
• Environment variables setup
• Automated tests

📈 API Versioning

API versions are specified in the URL path (/api/v1/). Breaking changes will be introduced in new versions with advance notice.