Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
julialeex
requested review from
a team and
stefanhengl
and removed request for
a team
|
|
||
| The fastest way to migrate is to give your AI coding agent the OpenAPI schema and let it update your code. You can download the schema from `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`) — look for the **Download OpenAPI** button. Then tell your agent to migrate your Deep Search API calls to the new `/api/` equivalents. | ||
|
|
||
| For a real-world example, see [this Amp thread](https://ampcode.com/threads/T-019c9bf7-e5bd-778e-b8c8-0796ce033784) migrating the [raycast-sourcegraph](https://github.com/bobheadxi/raycast-sourcegraph) extension from the old API to the new endpoints. |
There was a problem hiding this comment.
Can you also try with just this prompt? Curious if it works also 😁
Migrate the Deep Search API calls in this project from the deprecated /.api/deepsearch/v1 endpoints to the new Sourcegraph /api/deepsearch.v1.Service/ endpoints.
The main file to update is src/sourcegraph/deep-search/index.ts. Use the attached OpenAPI schema (@sourcesourcegraph-openapi.json) as the specification for the new API.
Also, did you try running the extension to make sure the migrated changes work correctly? happy to pair to try that out
There was a problem hiding this comment.
I just tried this prompt, down to pair later
There was a problem hiding this comment.
Should we tell them to point the agent to this doc page to? Meaning, should we treat this page as one giant migration prompt for humans and agents?
There was a problem hiding this comment.
yeah, though i worry it's a bit large since it includes the old schema
we should also remove the preview status of this page too, since it's currently hidden by default, to make it easier for the agent to access. with the migration guide on top and all the warnings i think it's fine for it to be discoverable
| - `404` - Not Found | ||
| - `500` - Internal Server Error | ||
|
|
||
| ## Migrating to the New Sourcegraph API |
There was a problem hiding this comment.
should we put this at the top?
There was a problem hiding this comment.
I think having this at the very end of the page makes the flow better? I added a new callout at the top; however, let me know if you still want this section at the top.
There was a problem hiding this comment.
I think having the migration at the top sets the expectations right when you land on the page, that we want you to migrate - a link is easy to miss/ignore
| ## Integrations and APIs | ||
|
|
||
| Integrations can use [Sourcegraph APIs](/api), such as the new Sourcegraph API and MCP server, to interact with Deep Search. | ||
| Integrations can use [Sourcegraph APIs](/api), such as the [new Sourcegraph API](/deep-search/api) and MCP server, to interact with Deep Search. |
There was a problem hiding this comment.
| Integrations can use [Sourcegraph APIs](/api), such as the [new Sourcegraph API](/deep-search/api) and MCP server, to interact with Deep Search. | |
| Integrations can use [Sourcegraph APIs](/api) and the [MCP server](/mcp) to interact with Deep Search. | |
| If you are using the experimental Deep Search API, please [follow our migration guide](/deep-search/api?preview). |
| - [ ] Remove the `X-Requested-With` header | ||
| - [ ] Update endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` | ||
| - [ ] Change all HTTP methods to `POST` | ||
| - [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) |
There was a problem hiding this comment.
This is not clear to me what that means? Why is it /-/? We are not switching to resource names but to rpc / operations on resources.
|
I tried to run this locally with Should we mention this guide on the top-level API page as well? It's quite hidden right now. |
3 participants
CLOSE CU-2424
Adds a new docs page at /api/migration that walks integrators through migrating to the new Sourcegraph API