REST API ReadME #3183
REST API ReadME #3183
Conversation
WalkthroughThe Synapse REST API README file has been significantly updated, changing its title and base URL while modifying local running instructions. Documentation enhancements include links to Swagger and GitBook, a concise overview of API functionality, and updated request examples. New endpoints for querying token information and validating user input have been introduced, and a contribution note encourages user involvement in documentation improvements. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (6)
packages/rest-api/README.md (6)
1-2: LGTM! Consider adding a note about the URL change.The updated title "Synapse REST API" is more concise and accurately reflects the content. The new base URL
https://api.synapseprotocol.com/is clearly stated.Consider adding a note to highlight the URL change for existing users, e.g.:
**Note:** The base URL has been updated from the previous Heroku endpoint. Please ensure you update your API calls accordingly.🧰 Tools
Markdownlint
2-2: null
Bare URL used(MD034, no-bare-urls)
5-8: LGTM! Consider adding more setup instructions.The updated command
yarn devfor running the API locally is clear and concise.Consider adding more detailed setup instructions for new contributors, such as:
## Local Development 1. Clone the repository 2. Install dependencies: `yarn install` 3. Run the API locally: `yarn dev`This would provide a more comprehensive guide for setting up the development environment.
10-16: Great addition of documentation links. Consider adding a brief endpoint overview.The inclusion of links to Swagger and GitBook documentation is excellent, providing users with comprehensive resources.
Consider adding a brief overview of the main endpoints available, e.g.:
## Available Endpoints - `/bridge`: Get quotes for cross-chain token bridges - `/swap`: Get quotes for token swaps - `/destinationTokens`: Get information about possible destination tokens - `/bridgeLimits`: Get minimum and maximum bridge amountsThis would give users a quick reference without needing to leave the README.
18-60: Excellent examples provided. Consider adding error handling.The bridge request example and JavaScript code snippets are clear and informative, providing valuable guidance for developers interacting with the API.
Consider adding basic error handling to the JavaScript examples, e.g.:
async function getBridgeQuote() { try { const response = await fetch('https://api.synapseprotocol.com/bridge?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&amount=100'); const data = await response.json(); console.log(data); } catch (error) { console.error('Error fetching bridge quote:', error); } }This would demonstrate best practices for handling potential API errors.
62-75: Great addition of new endpoint information. Consider adding response examples.The information about
/destinationTokensand/bridgeLimitsendpoints, along with usage examples, is a valuable addition to the README.Consider adding examples of the expected response format for these endpoints, e.g.:
// Example response for /destinationTokens { "destinationChains": [ { "chainId": 42161, "tokens": [ { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 } ] } ] }This would give developers a clearer understanding of the data they'll be working with.
🧰 Tools
LanguageTool
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...response.json(); ``` 2./bridgeLimits: This endpoint returns the minimum and m...(UNLIKELY_OPENING_PUNCTUATION)
Markdownlint
62-62: Punctuation: ':'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
Gitleaks
66-66: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
73-73: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
77-77: Consider expanding contribution guidelines.The brief instructions for contributing to the API documentation are helpful, but they could be more detailed to encourage and guide potential contributors.
Consider expanding the contribution guidelines, e.g.:
## Contributing We welcome contributions to improve the API and its documentation. To contribute: 1. Fork the repository 2. Create a new branch for your changes 3. Make your changes, ensuring you: - Include appropriate test coverage - Update relevant documentation (this README, Swagger, and GitBook) 4. Submit a pull request with a clear description of your changes For major changes, please open an issue first to discuss what you would like to change.This would provide a more comprehensive guide for potential contributors.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (1)
- packages/rest-api/README.md (1 hunks)
🧰 Additional context used
LanguageTool
packages/rest-api/README.md
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...response.json(); ``` 2./bridgeLimits: This endpoint returns the minimum and m...(UNLIKELY_OPENING_PUNCTUATION)
Markdownlint
packages/rest-api/README.md
62-62: Punctuation: ':'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
2-2: null
Bare URL used(MD034, no-bare-urls)
Gitleaks
packages/rest-api/README.md
66-66: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
73-73: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
| - \`rawParams\` (string) - Encoded hex string containing swap parameters | ||
| - \`maxAmountOutStr\` (string) - The maxAmountOut value formatted as a decimal string | ||
| ## REST API | ||
| The Synapse REST API provides a set of endpoints for quoting and executing cross-chain token swaps and bridges. It supports various functions including swap quotes, bridge quotes, transaction information retrieval, and token list management. | ||
|
|
||
| All \`/swap\` requests should be formatted like such: | ||
| ## Formatting Requests | ||
| Here's an example of how to format a bridge request: | ||
|
|
||
| \`/swap?chain=1&fromToken=USDC&toToken=DAI&amount=100\` | ||
| ```bash | ||
| /bridge?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&amount=100 | ||
| ``` | ||
|
|
||
| ## /bridge | ||
| To use this in a basic application: | ||
|
|
||
| which returns all transaction information | ||
| ```javascript | ||
| async function getBridgeQuote() { | ||
| const response = await fetch('https://api.synapseprotocol.com/bridge?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&amount=100'); | ||
| const data = await response.json(); | ||
| console.log(data); | ||
| } | ||
| getBridgeQuote(); | ||
| ``` | ||
|
|
||
| - \`feeAmount\` (object) - The fee amount for the swap. Contains: | ||
| - \`type\` (string) - Data type | ||
| - \`hex\` (string) - Fee amount encoded in hex | ||
| - \`feeConfig\` (array) - Fee configuration parameters, contains: | ||
| - \`0\` (number) - Gas price | ||
| - \`1\` (object) - Fee percentage denominator (hex encoded BigNumber) | ||
| - \`2\` (object) - Protocol fee percentage numerator (hex encoded BigNumber) | ||
| - \`routerAddress\` (string) - Address of the router contract | ||
| - \`maxAmountOut\` (object) - Maximum amount receivable from swap, structure same as above | ||
| - \`originQuery\` (object) - Original swap query parameters, contains: | ||
| - \`swapAdapter\` (string) - Swap adapter address | ||
| - \`tokenOut\` (string) - Address of output token | ||
| - \`minAmountOut\` (object) - Minimum output token amount | ||
| - \`deadline\` (object) - Expiry time | ||
| - \`rawParams\` (string) - Encoded hex params | ||
| - \`destQuery\` (object) - Destination swap query parameters, structure similar to originQuery above. | ||
| - \`maxAmountOutStr\` (string) - maxAmountOut as a decimal string. | ||
|
|
||
| All \`/bridge\` requests should be formatted like such: | ||
| ## Bridging | ||
|
|
||
| \`/bridge?fromChain=1&toChain=42161&fromToken=USDC&toToken=USDC&amount=1000000\` | ||
| 1. Get a Bridge Quote to confirm the expected amount out and the bridge route | ||
|
|
||
| ## /swapTxInfo | ||
| ```javascript | ||
| const quoteResponse = await fetch('https://api.synapseprotocol.com/bridge?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&amount=100'); | ||
| const quoteData = await quoteResponse.json(); | ||
| ``` | ||
|
|
||
| which returns the following | ||
| 2. Get the structured transaction information | ||
|
|
||
| - \`'data'\`: The binary data that forms the input to the transaction. | ||
| - \`'to'\`: The address of the Synapse Router (the synapse bridge contract) | ||
| ```javascript | ||
| const txInfoResponse = await fetch('https://api.synapseprotocol.com/bridgeTxInfo?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&amount=100&destAddress=0xcc78d2f004c9de9694ff6a9bbdee4793d30f3842'); | ||
| const txInfoData = await txInfoResponse.json(); | ||
| ``` | ||
|
|
||
| All \`/swapTxInfo\` requests should be formatted like such: | ||
| 3. Execute the transaction | ||
|
|
||
| \`/swap?chain=1&fromToken=USDC&toToken=DAI&amount=100\` | ||
| ```javascript | ||
| const provider = new ethers.providers.Web3Provider(window.ethereum); | ||
| const signer = provider.getSigner(); | ||
| const transaction = await signer.sendTransaction(txInfoData); | ||
| const receipt = await transaction.wait(); | ||
| ``` | ||
|
|
||
| ## /bridgeTxInfo | ||
| ## Other Functions: | ||
| 1. `/destinationTokens`: This endpoint provides information about possible destination tokens for a given source chain and token. It's useful for showing users their options when initiating a cross-chain transfer. | ||
|
|
||
| which returns the following | ||
| ```javascript | ||
| const response = await fetch('https://api.synapseprotocol.com/destinationTokens?fromChain=1&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'); | ||
| const destinationTokens = await response.json(); | ||
| ``` | ||
|
|
||
| - \`'data'\`: The binary data that forms the input to the transaction. | ||
| - \`'to'\`: The address of the Synapse Router (the synapse bridge contract) | ||
| 2. `/bridgeLimits`: This endpoint returns the minimum and maximum amounts that can be bridged for a specific token pair. It's helpful for validating user input and displaying available limits. | ||
|
|
||
| All \`/bridgeTxInfo\` requests should be formatted like such: | ||
| ```javascript | ||
| const limitsResponse = await fetch('https://api.synapseprotocol.com/bridgeLimits?fromChain=1&toChain=42161&fromToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831'); | ||
| const limitsData = await limitsResponse.json(); | ||
| ``` | ||
|
|
||
| \`/bridgeTxInfo?fromChain=1&toChain=42161&fromToken=USDC&toToken=USDC&amount=1000000&destAddress=0xcc78d2f004c9de9694ff6a9bbdee4793d30f3842\` | ||
| There are other additional functions that are included and documented in the Swagger documentation. Suggested changes to the API can be made by creating a new branch, making the changes, and opening a pull request. Any changes should include the appropriate test coverage and update the relevant documentation (this README, Swagger, and GitBook). |
There was a problem hiding this comment.
Address minor markdown issues and clarify example URLs.
There are a few minor markdown issues that can be addressed:
- Remove the trailing colon from the "Other Functions" heading on line 62.
- Use a proper markdown link for the base URL on line 2 instead of a bare URL.
Regarding the static analysis warnings about potential API keys:
The warnings for Generic API Keys on lines 66 and 73 are false positives. These are example API endpoints, not actual API keys. However, to avoid confusion, consider adding a note to clarify that these are example URLs, not real API keys.
Example:
**Note:** The URLs in the examples are for illustration purposes only and do not contain real API keys.🧰 Tools
LanguageTool
[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...response.json(); ``` 2./bridgeLimits: This endpoint returns the minimum and m...(UNLIKELY_OPENING_PUNCTUATION)
Markdownlint
62-62: Punctuation: ':'
Trailing punctuation in heading(MD026, no-trailing-punctuation)
2-2: null
Bare URL used(MD034, no-bare-urls)
Gitleaks
66-66: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
73-73: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
Deploying sanguine-fe with
|
| Latest commit: |
abdfe8e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0ffa8a0a.sanguine-fe.pages.dev |
| Branch Preview URL: | https://docs-rest-api-readme.sanguine-fe.pages.dev |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3183 +/- ##
===================================================
- Coverage 41.54443% 37.95792% -3.58651%
===================================================
Files 460 418 -42
Lines 25770 24240 -1530
Branches 357 82 -275
===================================================
- Hits 10706 9201 -1505
+ Misses 14326 14301 -25
Partials 738 738
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Updating the readme for the rest-api
Summary by CodeRabbit