Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixing REST API docs to include route changes #3401

Merged
merged 2 commits into from
Nov 19, 2024
Merged

Fixing REST API docs to include route changes #3401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd242d6
fixing docs to reflect changes to endpoint and add more clarity
Defi-Moses Nov 19, 2024
e5d43fb
language changes
Defi-Moses Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/bridge/docs/02-Bridge/02-REST-API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@ title: REST API

# REST API

Get read-only data from on-chain Synapse contracts, and generate Bridge and Swap quotes, plus additional transaction information.
The Synapse REST API is a read-only API that allows you to integrate the Synapse liquidity network into your application.

Through HTTP requests, developers can integrate Synapse cross-chain tokens and liquidity transfers dynamically into their applications. Developers can retrieve quotes, as well as generate the relevant call data for Synapse Bridges and Swaps. Example requests can be found below in the [API-docs](#api-docs) section.


The Synapse REST API is built on top of the [Synapse Bridge SDK](https://docs.synapseprotocol.com/docs/Bridge/SDK).


The API is available at [`https://api.synapseprotocol.com/`](https://api.synapseprotocol.com/).


## API-docs

Expand All @@ -17,6 +26,7 @@ Get read-only data from on-chain Synapse contracts, and generate Bridge and Swap
| Date | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2024‑10‑01 | [https://synapse-rest-api-v2.herokuapp.com/](https://synapse-rest-api-v2.herokuapp.com/) is no longer maintained and has been fully deprecated as of October 2024. |
| 2024‑11‑19 | [https://api.synapseprotocol.com/](https://api.synapseprotocol.com/) the /bridgeTxInfo endpoint has been consolidated into the /bridge endpoint, which now returns call data |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Complete the version history entry

The version history entry should mention both endpoint consolidations and provide clear migration guidance.

Update the entry to include both changes:

-| 2024‑11‑19 | [https://api.synapseprotocol.com/](https://api.synapseprotocol.com/) the /bridgeTxInfo endpoint has been consolidated into the /bridge endpoint, which now returns call data                   |
+| 2024‑11‑19 | [https://api.synapseprotocol.com/](https://api.synapseprotocol.com/) - The `/bridgeTxInfo` and `/swapTxInfo` endpoints have been consolidated into the `/bridge` and `/swap` endpoints respectively. The consolidated endpoints now return transaction data directly. Users should update their integrations accordingly. |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| 2024‑11‑19 | [https://api.synapseprotocol.com/](https://api.synapseprotocol.com/) the /bridgeTxInfo endpoint has been consolidated into the /bridge endpoint, which now returns call data |
| 2024‑11‑19 | [https://api.synapseprotocol.com/](https://api.synapseprotocol.com/) - The `/bridgeTxInfo` and `/swapTxInfo` endpoints have been consolidated into the `/bridge` and `/swap` endpoints respectively. The consolidated endpoints now return transaction data directly. Users should update their integrations accordingly. |


## Support

Expand Down
4 changes: 2 additions & 2 deletions packages/rest-api/src/routes/bridgeTxInfoRoute.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ const router: express.Router = express.Router()
* @openapi
* /bridgeTxInfo:
* get:
* summary: Get bridge transaction information
* description: Retrieve transaction information for bridging tokens between chains
* summary: "[Deprecated] in favor of using the /bridge endpoint, which now returns call data"
* description: "[Deprecated] Originally used to get Bridge transaction information"
* parameters:
* - in: query
* name: fromChain
Expand Down
4 changes: 2 additions & 2 deletions packages/rest-api/src/routes/swapTxInfoRoute.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ const router: express.Router = express.Router()
* @openapi
* /swapTxInfo:
* get:
* summary: Get swap transaction information
* description: Retrieve transaction information for swapping tokens on a specific chain
* summary: "[Deprecated] in favor of using the /swap endpoint, which now returns call data
* description: "[Deprecated] Originally used to get Swap transaction information
Comment on lines +21 to +22
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Enhance deprecation handling with proper HTTP headers and migration guidance.

While the documentation indicates deprecation, the implementation should follow API deprecation best practices:

  1. Add a deprecation warning header to responses
  2. Include a sunset date
  3. Provide specific migration steps to the new /swap endpoint

Consider implementing these changes:

 router.get(
   '/',
   normalizeNativeTokenAddress(['fromToken', 'toToken']),
   checksumAddresses(['fromToken', 'toToken']),
+  (req, res, next) => {
+    res.set({
+      'Deprecation': 'true',
+      'Sunset': '2025-01-01',
+      'Link': '</swap>; rel="successor-version"',
+      'Warning': '299 - "This endpoint is deprecated. Please migrate to /swap endpoint which provides the same functionality plus call data."'
+    });
+    next();
+  },
   [
     check('chain')
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* summary: "[Deprecated] in favor of using the /swap endpoint, which now returns call data
* description: "[Deprecated] Originally used to get Swap transaction information
* summary: "[Deprecated] in favor of using the /swap endpoint, which now returns call data
* description: "[Deprecated] Originally used to get Swap transaction information
router.get(
'/',
normalizeNativeTokenAddress(['fromToken', 'toToken']),
checksumAddresses(['fromToken', 'toToken']),
(req, res, next) => {
res.set({
'Deprecation': 'true',
'Sunset': '2025-01-01',
'Link': '</swap>; rel="successor-version"',
'Warning': '299 - "This endpoint is deprecated. Please migrate to /swap endpoint which provides the same functionality plus call data."'
});
next();
},
[
check('chain')

* parameters:
* - in: query
* name: chain
Expand Down
8 changes: 4 additions & 4 deletions packages/rest-api/swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -396,8 +396,8 @@
},
"/bridgeTxInfo": {
"get": {
"summary": "Get bridge transaction information",
"description": "Retrieve transaction information for bridging tokens between chains",
"summary": "[Deprecated] in favor of using the /bridge endpoint, which now returns call data",
"description": "[Deprecated] Originally used to get Bridge transaction information",
"parameters": [
{
"in": "query",
Expand Down Expand Up @@ -1345,8 +1345,8 @@
},
"/swapTxInfo": {
"get": {
"summary": "Get swap transaction information",
"description": "Retrieve transaction information for swapping tokens on a specific chain",
"summary": "[Deprecated] in favor of using the /swap endpoint, which now returns call data",
"description": "[Deprecated] Originally used to get Swap transaction information",
"parameters": [
{
"in": "query",
Expand Down
Loading