Feature Request: Version-Based API Query and Batch Requests for JSON-RPC 2.0

[lithbitren]

Hi docs.rs team,

This API will provide precise, secure, and efficient metadata access for LLMs and tools, addressing the above issues.

I suggest adding the following JSON-RPC 2.0 APIs to improve metadata query precision and efficiency:

Core Requirements

1. Query API Documentation by Version
   Method Name: get_api_documentation

Parameters:

crate_name (required): Name of the crate (string).
version (optional): Specific version (string). If omitted, the latest version is used.
Example Request (with version):

{  
  "jsonrpc": "2.0",  
  "method": "get_api_documentation",  
  "params": {  
    "crate_name": "serde",  
    "version": "1.0.0"  
  },  
  "id": 1  
}  

Success Response (valid crate and version):

{  
  "jsonrpc": "2.0",  
  "result": {  
    "crate_name": "serde",  
    "version": "1.0.0",  
    "api_documentation": [  
      {  
        "name": "Serializer",  
        "description": "Serialization struct",  
        "parameters": [...]  
      }  
    ]  
  },  
  "id": 1  
}  

Error Responses:

Crate does not exist:

{  
  "jsonrpc": "2.0",  
  "error": {  
    "code": -32001,  
    "message": "Crate 'nonexistent_crate' does not exist"  
  },  
  "id": 1  
}  

Invalid version:

{  
  "jsonrpc": "2.0",  
  "error": {  
    "code": -32002,  
    "message": "Version '2.0.0' for crate 'serde' is invalid"  
  },  
  "id": 1  
}

API not found:

{  
  "jsonrpc": "2.0",  
  "error": {  
    "code": -32003,  
    "message": "API 'invalid_api' not found in crate 'serde' v1.0.0"  
  },  
  "id": 1  
}  

2. Fuzzy Search with Pagination
   Method Name: search_api

Parameters:

query (required): Search keyword (string).
limit (optional): Number of results (default 10, max 200).
offset (optional): Pagination offset (default 0).
Example Request:

{  
  "jsonrpc": "2.0",  
  "method": "search_api",  
  "params": {  
    "query": "serde",  
    "limit": 5  
  },  
  "id": 2  
}  

Success Response:

{  
  "jsonrpc": "2.0",  
  "result": [  
    {  
      "crate_name": "serde",  
      "version": "1.0.0",  
      "api_name": "Serializer",  
      "description": "..."  
    },  
    ...  
  ],  
  "id": 2  
}

3. Batch Requests
   Example Request:

[  
  {  
    "jsonrpc": "2.0",  
    "method": "get_api_documentation",  
    "params": {  
      "crate_name": "serde"  
    },  
    "id": 1  
  },  
  {  
    "jsonrpc": "2.0",  
    "method": "search_api",  
    "params": {  
      "query": "rust"  
    },  
    "id": 2  
  }  
]

Response Format:

[  
  {  
    "jsonrpc": "2.0",  
    "result": { ... },  
    "id": 1  
  },  
  {  
    "jsonrpc": "2.0",  
    "result": [ ... ],  
    "id": 2  
  }  
]  

Key Advantages
Reduce Resource Usage:
Precise queries avoid parsing full HTML pages.
Batch requests lower network overhead.
Improve Accuracy:
Version control ensures documentation matches the requested version.
Standard error codes (e.g., -32001) simplify error handling.

[syphar]

Thank you for your idea!

So, generally docs.rs doesn't have any direct access to the documentation metadata. Simplified we only run cargo doc and store & serve the HTML.

Our strategy for programmatic access to the documentation details is #1285 , where we would generate the rustdoc JSON output format and host it side-by-side to the HTML documentation. This would solve your requirement about the download of the full documentation. This feature is blocked until the rustdoc JSON format is stable, and then trivial to implement.

I could also imagine docs.rs providing other APIs on top of the JSON file, though these likely won't be JSON-RPC but REST. But these would also be tricky to implement, we have crates with ~5 million HTML pages of documentation, making these searchable / queryable via API is a hard problem to solve.

Until then, and LLM can also use the HTML archive that can be downloaded for each version.

[lithbitren]

Thank you for your idea!

So, generally docs.rs doesn't have any direct access to the documentation metadata. Simplified we only run cargo doc and store & serve the HTML.

Our strategy for programmatic access to the documentation details is #1285 , where we would generate the rustdoc JSON output format and host it side-by-side to the HTML documentation. This would solve your requirement about the download of the full documentation. This feature is blocked until the rustdoc JSON format is stable, and then trivial to implement.

I could also imagine docs.rs providing other APIs on top of the JSON file, though these likely won't be JSON-RPC but REST. But these would also be tricky to implement, we have crates with ~5 million HTML pages of documentation, making these searchable / queryable via API is a hard problem to solve.

Until then, and LLM can also use the HTML archive that can be downloaded for each version.

Thank you for your reply.

REST API would also work for us. Even better, if we could just confirm whether an API path exists, that would be sufficient. LLMs typically only need to know the path and data type to function properly.

If searching the entire documentation causes too much server load, maybe limiting the search to just paths could reduce the pressure significantly.

While the total documentation volume is large, commonly used libraries might actually be limited in number. Adding some caching could greatly improve performance.

[syphar]

What do you mean with "api path" and "search for paths"?

[lithbitren]

What do you mean with "api path" and "search for paths"?

the "path" I mentioned specifically refers to API call paths such as the namespace path (e.g., crate::module::function in Rust). These paths identify specific functions, structs, or methods, to quickly confirm the existence of such paths via an API and retrieve their data types (e.g., function, struct) to optimize LLM inference efficiency.

[syphar]

Ah ok, the we're back to my general API idea based on the. rustdoc JSON output.

First step will be building it, the it's also possible for you to just build a small wrapper around a download of the export.

[lithbitren]

Ah ok, the we're back to my general API idea based on the. rustdoc JSON output.

First step will be building it, the it's also possible for you to just build a small wrapper around a download of the export.

I came up with this issue idea after seeing this repository: https://github.com/d6e/cratedocs-mcp. It would be great if the official API were available. Previously, I manually queried docs.rs and modified the LLM prompt, but the efficiency was not very good.