diff options
| -rw-r--r-- | .prettierignore | 1 | ||||
| -rw-r--r-- | packages/sra-api/.discharge.json | 2 | ||||
| -rw-r--r-- | packages/sra-api/README.md | 6 | ||||
| -rw-r--r-- | packages/sra-api/build_scripts/buildJson.ts | 1 | ||||
| -rw-r--r-- | packages/sra-api/package.json | 1 | ||||
| -rw-r--r-- | packages/sra-api/public/api.json | 1 | ||||
| -rw-r--r-- | packages/sra-api/public/index.html | 24 | ||||
| -rw-r--r-- | packages/sra-api/src/api.ts | 8 | ||||
| -rw-r--r-- | packages/sra-api/src/md/introduction.md | 44 | ||||
| -rw-r--r-- | packages/sra-api/src/parameters.ts | 4 | ||||
| -rw-r--r-- | yarn.lock | 4 |
11 files changed, 58 insertions, 38 deletions
diff --git a/.prettierignore b/.prettierignore index e486d7573..3a69fc8de 100644 --- a/.prettierignore +++ b/.prettierignore @@ -15,6 +15,7 @@ lib /packages/contract-wrappers/src/artifacts /packages/order-watcher/src/artifacts /packages/metacoin/artifacts +/packages/sra-api/public/ /packages/contract-wrappers/test/artifacts /packages/order-watcher/test/artifacts /packages/migrations/artifacts/1.0.0 diff --git a/packages/sra-api/.discharge.json b/packages/sra-api/.discharge.json index 541ce4d70..df2cce0f4 100644 --- a/packages/sra-api/.discharge.json +++ b/packages/sra-api/.discharge.json @@ -1,6 +1,6 @@ { "domain": "sra-api", - "build_command": "yarn build-site", + "build_command": "yarn build-json", "upload_directory": "public", "index_key": "index.html", "error_key": "index.html", diff --git a/packages/sra-api/README.md b/packages/sra-api/README.md index 5b5475dc0..dec66c498 100644 --- a/packages/sra-api/README.md +++ b/packages/sra-api/README.md @@ -66,12 +66,6 @@ PKG=@0xproject/sra-api yarn watch We also [host a static HTML version of the docs on S3](http://sra-api.s3-website-us-east-1.amazonaws.com/) for easy sharing. -To build the website run - -``` -yarn build-site -``` - To build and deploy the site run ``` diff --git a/packages/sra-api/build_scripts/buildJson.ts b/packages/sra-api/build_scripts/buildJson.ts index ea99a0823..b92b5172b 100644 --- a/packages/sra-api/build_scripts/buildJson.ts +++ b/packages/sra-api/build_scripts/buildJson.ts @@ -4,3 +4,4 @@ import { api } from '../src'; const apiJson = JSON.stringify(api); writeFileSync('lib/api.json', apiJson); +writeFileSync('public/api.json', apiJson); diff --git a/packages/sra-api/package.json b/packages/sra-api/package.json index 5fed56303..4a8526a28 100644 --- a/packages/sra-api/package.json +++ b/packages/sra-api/package.json @@ -18,7 +18,6 @@ "test:circleci": "yarn test:coverage", "clean": "shx rm -rf lib", "build": "tsc && yarn build-json", - "build-site": "yarn build && redoc-cli bundle lib/api.json --output public/index.html", "build-json": "ts-node build_scripts/buildJson.ts", "build-json:watch": "chokidar 'src/**/*' -c 'yarn build-json' ", "deploy-site": "discharge deploy" diff --git a/packages/sra-api/public/api.json b/packages/sra-api/public/api.json new file mode 100644 index 000000000..36b08ad1a --- /dev/null +++ b/packages/sra-api/public/api.json @@ -0,0 +1 @@ +{"openapi":"3.0.0","info":{"version":"2.0.0","title":"Standard Relayer REST API","description":"# Testing\n\nUse the [sra-report](https://github.com/0xProject/0x-monorepo/tree/development/packages/sra-report) command line tool to test your API for SRA compliance.\n\n# Schemas\n\nThe [JSON schemas](http://json-schema.org/) for the API payloads and responses can be found in [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas). Examples of each payload and response can be found in the library's [test suite](https://github.com/0xProject/0x.js/blob/development/packages/json-schemas/test/schema_test.ts#L1).\n\n```bash\nnpm install @0xproject/json-schemas --save\n```\n\nYou can easily validate your API's payloads and responses using the [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas) package:\n\n```js\nimport {SchemaValidator, ValidatorResult, schemas} from '@0xproject/json-schemas';\n\nconst {relayerApiTokenPairsResponseSchema} = schemas;\nconst validator = new SchemaValidator();\n\nconst tokenPairsResponse = {\n ...\n};\nconst validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, relayerApiTokenPairsResponseSchema);\n```\n\n# Pagination\n\nRequests that return potentially large collections should respond to the **?page** and **?perPage** parameters. For example:\n\n```bash\n$ curl https://api.example-relayer.com/v2/asset_pairs?page=3&perPage=20\n```\n\nPage numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) `perPage` value, the response can return a validation error as specified in the [errors section](#section/Errors). If the query specifies a `page` that does not exist (ie. there are not enough `records`), the response should just return an empty `records` array.\n\nAll endpoints that are paginated should return a `total`, `page`, `perPage` and a `records` value in the top level of the collection. The value of `total` should be the total number of records for a given query, whereas `records` should be an array representing the response to the query for that page. `page` and `perPage`, are the same values that were specified in the request. See the note in [miscellaneous](#section/Misc.) about formatting `snake_case` vs. `lowerCamelCase`.\n\nThese requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/orders`](#operation/getOrders), [`/v2/fee_recipients`](#operation/getFeeRecipients) and [`/v2/orderbook`](#operation/getOrderbook) endpoints.\n\n# Network Id\n\nAll requests should be able to specify a **?networkId** query param for all supported networks. For example:\n\n```bash\n$ curl https://api.example-relayer.com/v2/asset_pairs?networkId=1\n```\n\nIf the query param is not provided, it should default to **1** (mainnet).\n\nNetworks and their Ids:\n\n| Network Id | Network Name |\n| ---------- | ------------ |\n| 1 | Mainnet |\n| 42 | Kovan |\n| 3 | Ropsten |\n| 4 | Rinkeby |\n\nIf a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example:\n\n```json\n{\n \"code\": 100,\n \"reason\": \"Validation failed\",\n \"validationErrors\": [\n {\n \"field\": \"networkId\",\n \"code\": 1006,\n \"reason\": \"Network id 42 is not supported\"\n }\n ]\n}\n```\n\n# Link Header\n\nA [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging\nFor example:\n\n```bash\nLink: <https://api.example-relayer.com/v2/asset_pairs?page=3&perPage=20>; rel=\"next\",\n<https://api.github.com/user/repos?page=10&perPage=20>; rel=\"last\"\n```\n\nThis `Link` response header contains one or more Hypermedia link relations.\n\nThe possible `rel` values are:\n\n| Name | Description |\n| ----- | ------------------------------------------------------------- |\n| next | The link relation for the immediate next page of results. |\n| last | The link relation for the last page of results. |\n| first | The link relation for the first page of results. |\n| prev | The link relation for the immediate previous page of results. |\n\n# Rate Limits\n\nRate limit guidance for clients can be optionally returned in the response headers:\n\n| Header Name | Description |\n| --------------------- | ---------------------------------------------------------------------------- |\n| X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. |\n| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |\n| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |\n\nFor example:\n\n```bash\n$ curl -i https://api.example-relayer.com/v2/asset_pairs\nHTTP/1.1 200 OK\nDate: Mon, 20 Oct 2017 12:30:06 GMT\nStatus: 200 OK\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 56\nX-RateLimit-Reset: 1372700873\n```\n\nWhen a rate limit is exceeded, a status of **429 Too Many Requests** should be returned.\n\n# Errors\n\nUnless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.\n\n## Common error codes\n\n| Code | Reason |\n| ---- | --------------------------------------- |\n| 400 | Bad Request – Invalid request format |\n| 404 | Not found |\n| 429 | Too many requests - Rate limit exceeded |\n| 500 | Internal Server Error |\n| 501 | Not Implemented |\n\n## Error reporting format\n\nFor all **400** responses, see the [error response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_error_response_schema.ts#L1).\n\n```json\n{\n \"code\": 101,\n \"reason\": \"Validation failed\",\n \"validationErrors\": [\n {\n \"field\": \"maker\",\n \"code\": 1002,\n \"reason\": \"Invalid address\"\n }\n ]\n}\n```\n\nGeneral error codes:\n\n```bash\n100 - Validation Failed\n101 - Malformed JSON\n102 - Order submission disabled\n103 - Throttled\n```\n\nValidation error codes:\n\n```bash\n1000 - Required field\n1001 - Incorrect format\n1002 - Invalid address\n1003 - Address not supported\n1004 - Value out of range\n1005 - Invalid signature or hash\n1006 - Unsupported option\n```\n\n# Asset Data Encoding\n\nAs we now support multiple [token transfer proxies](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#assetproxy), the identifier of which proxy to use for the token transfer must be encoded, along with the token information. Each proxy in 0x v2 has a unique identifier. If you're using 0x.js there will be helper methods for this [encoding](https://0xproject.com/docs/0x.js#zeroEx-encodeERC20AssetData) and [decoding](https://0xproject.com/docs/0x.js#zeroEx-decodeAssetProxyId).\n\nThe identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector).\n\n```js\n// ERC20 Proxy ID 0xf47261b0\nbytes4(keccak256('ERC20Token(address)'));\n// ERC721 Proxy ID 0x08e937fa\nbytes4(keccak256('ERC721Token(address,uint256)'));\n```\n\nAsset data is encoded using [ABI encoding](https://solidity.readthedocs.io/en/develop/abi-spec.html).\n\nFor example, encoding the ERC20 token contract (address: 0x1dc4c1cefef38a777b15aa20260a54e584b16c48) using the ERC20 Transfer Proxy (id: 0xf47261b0) would be:\n\n```bash\n0xf47261b00000000000000000000000001dc4c1cefef38a777b15aa20260a54e584b16c48\n```\n\nEncoding the ERC721 token contract (address: `0x371b13d97f4bf77d724e78c16b7dc74099f40e84`), token id (id: `99`, which hex encoded is `0x63`) and the ERC721 Transfer Proxy (id: 0x08e937fa) would be:\n\n```bash\n0x08e937fa000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063\n```\n\nFor more information see [the Asset Proxy](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#erc20proxy) section of the v2 spec and the [Ethereum ABI Spec](https://solidity.readthedocs.io/en/develop/abi-spec.html).\n\n# Meta Data in Order Responses\n\nIn v2 of the standard relayer API we added the `metaData` field. It is meant to provide a standard place for relayers to put optional, custom or non-standard fields that may of interest to the consumer of the API.\n\nA good example of such a field is `remainingTakerAssetAmount`, which is a convenience field that communicates how much of a 0x order is potentially left to be filled. Unlike the other fields in a 0x order, it is not guaranteed to be correct as it is derived from whatever mechanism the implementer (ie. the relayer) is using. While convenient for prototyping and low stakes situations, we recommend validating the value of the field by checking the state of the blockchain yourself, such as by using [Order Watcher](https://0xproject.com/wiki#0x-OrderWatcher).\n\n# Misc.\n\n* All requests and responses should be of **application/json** content type\n* All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 token would show up as selling `'1000000000000000000'` units by this API).\n* All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the `0x` prefix.\n* All parameters are to be written in `lowerCamelCase`.\n","license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"}},"paths":{"/v2/asset_pairs":{"get":{"description":"Retrieves a list of available asset pairs and the information required to trade them (in any order). Setting only `assetDataA` or `assetDataB` returns pairs filtered by that asset only.","operationId":"getAssetPairs","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}},{"name":"page","in":"query","description":"The number of the page to request in the collection.","example":3,"schema":{"type":"number"}},{"name":"perPage","in":"query","description":"The number of records to return per page.","example":10,"schema":{"type":"number"}},{"name":"assetDataA","in":"query","description":"The assetData value for the first asset in the pair.","example":"0xf47261b04c32345ced77393b3530b1eed0f346429d","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"assetDataB","in":"query","description":"The assetData value for the second asset in the pair.","example":"0x0257179264389b814a946f3e92105513705ca6b990","schema":{"$ref":"#/components/schemas/hexSchema"}}],"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"Returns a collection of available asset pairs with some meta info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiAssetDataPairsResponseSchema"},"example":{"total":43,"page":1,"perPage":100,"records":[{"assetDataA":{"minAmount":"0","maxAmount":"10000000000000000000","precision":5,"assetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d"},"assetDataB":{"minAmount":"0","maxAmount":"50000000000000000000","precision":5,"assetData":"0x0257179264389b814a946f3e92105513705ca6b990"}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/orders":{"get":{"description":"Retrieves a list of orders given query parameters. This endpoint should be [paginated](#section/Pagination). For querying an entire orderbook snapshot, the [orderbook endpoint](#operation/getOrderbook) is recommended. If both makerAssetData and takerAssetData are specified, returned orders will be sorted by price determined by (takerTokenAmount/makerTokenAmount) in ascending order. By default, orders returned by this endpoint are unsorted.","operationId":"getOrders","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}},{"name":"page","in":"query","description":"The number of the page to request in the collection.","example":3,"schema":{"type":"number"}},{"name":"perPage","in":"query","description":"The number of records to return per page.","example":10,"schema":{"type":"number"}},{"name":"makerAssetProxyId","in":"query","description":"The maker [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: \"0xf47261b0\" for ERC20, \"0x02571792\" for ERC721).","example":"0xf47261b0","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"takerAssetProxyId","in":"query","description":"The taker asset [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: \"0xf47261b0\" for ERC20, \"0x02571792\" for ERC721).","example":"0x02571792","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"makerAssetAddress","in":"query","description":"The contract address for the maker asset.","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"takerAssetAddress","in":"query","description":"The contract address for the taker asset.","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"exchangeAddress","in":"query","description":"Same as exchangeAddress in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"senderAddress","in":"query","description":"Same as senderAddress in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"makerAssetData","in":"query","description":"Same as makerAssetData in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"takerAssetData","in":"query","description":"Same as takerAssetData in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"traderAssetData","in":"query","description":"Same as traderAssetData in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"makerAddress","in":"query","description":"Same as makerAddress in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"traderAddress","in":"query","description":"Same as traderAddress in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}},{"name":"feeRecipientAddress","in":"query","description":"Same as feeRecipientAddress in the [0x Protocol v2 Specification](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#order-message-format)","example":"0xe41d2489571d322189246dafa5ebde1f4699f498","schema":{"$ref":"#/components/schemas/addressSchema"}}],"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"A collection of 0x orders with meta-data as specified by query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiOrdersResponseSchema"},"example":{"total":984,"page":1,"perPage":100,"records":[{"order":{"makerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","takerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"10000000000000000","takerAssetAmount":"20000000000000000","makerFee":"100000000000000","takerFee":"200000000000000","expirationTimeSeconds":"1532560590","salt":"1532559225","makerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","takerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","signature":"0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"},"metaData":{}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/order/{orderHash}":{"get":{"description":"Retrieves the 0x order with meta info that is associated with the hash.","operationId":"getOrder","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}},{"name":"orderHash","in":"path","description":"The hash of the desired 0x order.","example":"0xd4b103c42d2512eef3fee775e097f044291615d25f5d71e0ac70dbd49d223591","schema":{"$ref":"#/components/schemas/orderHashSchema"}}],"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"The order and meta info associated with the orderHash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiOrderSchema"},"example":{"order":{"makerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","takerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"10000000000000000","takerAssetAmount":"20000000000000000","makerFee":"100000000000000","takerFee":"200000000000000","expirationTimeSeconds":"1532560590","salt":"1532559225","makerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","takerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","signature":"0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"},"metaData":{}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/orderbook":{"get":{"description":"Retrieves the orderbook for a given asset pair. This endpoint should be [paginated](#section/Pagination). Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted by _taker fee price_ which is defined as the **takerFee** divided by **takerTokenAmount**. After _taker fee price_, orders are to be sorted by expiration in ascending order. The way pagination works for this endpoint is that the **page** and **perPage** query params apply to both `bids` and `asks` collections, and if `page` * `perPage` > `total` for a certain collection, the `records` for that collection should just be empty. ","operationId":"getOrderbook","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}},{"name":"page","in":"query","description":"The number of the page to request in the collection.","example":3,"schema":{"type":"number"}},{"name":"perPage","in":"query","description":"The number of records to return per page.","example":10,"schema":{"type":"number"}},{"name":"baseAssetData","in":"query","description":"assetData (makerAssetData or takerAssetData) designated as the base currency in the [currency pair calculation](https://en.wikipedia.org/wiki/Currency_pair) of price.","required":true,"example":"0xf47261b04c32345ced77393b3530b1eed0f346429d","schema":{"$ref":"#/components/schemas/hexSchema"}},{"name":"quoteAssetData","in":"query","description":"assetData (makerAssetData or takerAssetData) designated as the quote currency in the currency pair calculation of price (required).","required":true,"example":"0xf47261b04c32345ced77393b3530b1eed0f346429d","schema":{"$ref":"#/components/schemas/hexSchema"}}],"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"The sorted order book for the specified asset pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiOrderbookResponseSchema"},"example":{"bids":{"total":325,"page":2,"perPage":100,"records":[{"order":{"makerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","takerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"10000000000000000","takerAssetAmount":"20000000000000000","makerFee":"100000000000000","takerFee":"200000000000000","expirationTimeSeconds":"1532560590","salt":"1532559225","makerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","takerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","signature":"0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"},"metaData":{}}]},"asks":{"total":500,"page":2,"perPage":100,"records":[{"order":{"makerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","takerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"20000000000000000","takerAssetAmount":"10000000000000000","makerFee":"200000000000000","takerFee":"100000000000000","expirationTimeSeconds":"1532560590","salt":"1532559225","makerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","takerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","signature":"0x013842a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b3518891"},"metaData":{}}]}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/order_config":{"get":{"description":"Relayers have full discretion over the orders that they are willing to host on their orderbooks (e.g what fees they charge, etc...). In order for traders to discover their requirements programmatically, they can send an incomplete order to this endpoint and receive the missing fields, specifc to that order. This gives relayers a large amount of flexibility to tailor fees to unique traders, trading pairs and volume amounts. Submit a partial order and receive information required to complete the order: `senderAddress`, `feeRecipientAddress`, `makerFee`, `takerFee`. ","operationId":"getOrderConfig","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}}],"requestBody":{"description":"The fields of a 0x order the relayer may want to decide what configuration to send back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiOrderConfigPayloadSchema"},"example":{"makerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","takerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"10000000000000000","takerAssetAmount":"20000000000000000","makerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","takerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","expirationTimeSeconds":"1532560590"}}}},"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"The additional fields necessary in order to submit an order to the relayer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiOrderConfigResponseSchema"},"example":{"senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","makerFee":"100000000000000","takerFee":"200000000000000"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/fee_recipients":{"get":{"description":"Retrieves a collection of all fee recipient addresses for a relayer. This endpoint should be [paginated](#section/Pagination).","operationId":"getFeeRecipients","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}},{"name":"page","in":"query","description":"The number of the page to request in the collection.","example":3,"schema":{"type":"number"}},{"name":"perPage","in":"query","description":"The number of records to return per page.","example":10,"schema":{"type":"number"}}],"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"A collection of all used fee recipient addresses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiFeeRecipientsResponseSchema"},"example":{"total":3,"page":1,"perPage":10,"records":["0x6eC92694ea172ebC430C30fa31De87620967A082","0x9e56625509c2f60af937f23b7b532600390e8c8b","0xa2b31dacf30a9c50ca473337c01d8a201ae33e32"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}},"/v2/order":{"post":{"description":"Submit a signed order to the relayer.","operationId":"postOrder","parameters":[{"name":"networkId","in":"query","description":"The id of the Ethereum network","example":42,"schema":{"type":"number"}}],"requestBody":{"description":"A valid signed 0x order based on the schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/signedOrderSchema"},"example":{"makerAddress":"0x9e56625509c2f60af937f23b7b532600390e8c8b","takerAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","feeRecipientAddress":"0xb046140686d052fff581f63f8136cce132e857da","senderAddress":"0xa2b31dacf30a9c50ca473337c01d8a201ae33e32","makerAssetAmount":"10000000000000000","takerAssetAmount":"20000000000000000","makerFee":"100000000000000","takerFee":"200000000000000","expirationTimeSeconds":"1532560590","salt":"1532559225","makerAssetData":"0xf47261b04c32345ced77393b3530b1eed0f346429d","takerAssetData":"0x0257179264389b814a946f3e92105513705ca6b990","exchangeAddress":"0x12459c951127e0c374ff9105dda097662a027093","signature":"0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"}}}},"responses":{"200":{"headers":{"X-Rate-Limit-Limit":{"description":"The maximum number of requests you're permitted to make per hour.","schema":{"type":"integer"}},"X-Rate-Limit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer"}},"X-Rate-Limit-Reset":{"description":"The time at which the current rate limit window resets in UTC epoch seconds.","schema":{"type":"integer"}}},"description":"OK","content":{}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/relayerApiErrorResponseSchema"},"example":{"code":100,"reason":"Validation failed","validationErrors":[{"field":"networkId","code":1006,"reason":"Network id 42 is not supported"}]}}}},"404":{"description":"Not found"},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal Server Error"},"501":{"description":"Not implemented."}}}}},"components":{"schemas":{"numberSchema":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"},"addressSchema":{"type":"string","pattern":"^0x[0-9a-f]{40}$"},"hexSchema":{"type":"string","pattern":"^0x(([0-9a-f][0-9a-f])+)?$"},"orderHashSchema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"orderSchema":{"properties":{"makerAddress":{"$ref":"#/components/schemas/addressSchema"},"takerAddress":{"$ref":"#/components/schemas/addressSchema"},"makerFee":{"$ref":"#/components/schemas/numberSchema"},"takerFee":{"$ref":"#/components/schemas/numberSchema"},"senderAddress":{"$ref":"#/components/schemas/addressSchema"},"makerAssetAmount":{"$ref":"#/components/schemas/numberSchema"},"takerAssetAmount":{"$ref":"#/components/schemas/numberSchema"},"makerAssetData":{"$ref":"#/components/schemas/hexSchema"},"takerAssetData":{"$ref":"#/components/schemas/hexSchema"},"salt":{"$ref":"#/components/schemas/numberSchema"},"exchangeAddress":{"$ref":"#/components/schemas/addressSchema"},"feeRecipientAddress":{"$ref":"#/components/schemas/addressSchema"},"expirationTimeSeconds":{"$ref":"#/components/schemas/numberSchema"}},"required":["makerAddress","takerAddress","makerFee","takerFee","senderAddress","makerAssetAmount","takerAssetAmount","makerAssetData","takerAssetData","salt","exchangeAddress","feeRecipientAddress","expirationTimeSeconds"],"type":"object"},"signedOrderSchema":{"allOf":[{"$ref":"#/components/schemas/orderSchema"},{"properties":{"signature":{"$ref":"#/components/schemas/hexSchema"}},"required":["signature"]}]},"signedOrdersSchema":{"type":"array","items":{"$ref":"#/components/schemas/signedOrderSchema"}},"ordersSchema":{"type":"array","items":{"$ref":"#/components/schemas/orderSchema"}},"paginatedCollectionSchema":{"type":"object","properties":{"total":{"type":"number"},"perPage":{"type":"number"},"page":{"type":"number"}},"required":["total","perPage","page"]},"relayerApiErrorResponseSchema":{"type":"object","properties":{"code":{"type":"integer","minimum":100,"maximum":103},"reason":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"integer","minimum":1000,"maximum":1006},"reason":{"type":"string"}},"required":["field","code","reason"]}}},"required":["code","reason"]},"relayerApiFeeRecipientsResponseSchema":{"type":"object","allOf":[{"$ref":"#/components/schemas/paginatedCollectionSchema"},{"properties":{"records":{"$ref":"#/components/schemas/addressSchema"}},"required":["records"]}]},"relayerApiOrderSchema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/orderSchema"},"metaData":{"type":"object"}},"required":["order","metaData"]},"relayerApiOrdersSchema":{"type":"array","items":{"$ref":"#/components/schemas/relayerApiOrderSchema"}},"relayerApiOrderConfigPayloadSchema":{"type":"object","properties":{"makerAddress":{"$ref":"#/components/schemas/addressSchema"},"takerAddress":{"$ref":"#/components/schemas/addressSchema"},"makerAssetAmount":{"$ref":"#/components/schemas/numberSchema"},"takerAssetAmount":{"$ref":"#/components/schemas/numberSchema"},"makerAssetData":{"$ref":"#/components/schemas/hexSchema"},"takerAssetData":{"$ref":"#/components/schemas/hexSchema"},"exchangeAddress":{"$ref":"#/components/schemas/addressSchema"},"expirationTimeSeconds":{"$ref":"#/components/schemas/numberSchema"}},"required":["makerAddress","takerAddress","makerAssetAmount","takerAssetAmount","makerAssetData","takerAssetData","exchangeAddress","expirationTimeSeconds"]},"relayerApiOrderConfigResponseSchema":{"type":"object","properties":{"makerFee":{"$ref":"#/components/schemas/numberSchema"},"takerFee":{"$ref":"#/components/schemas/numberSchema"},"feeRecipientAddress":{"$ref":"#/components/schemas/addressSchema"},"senderAddress":{"$ref":"#/components/schemas/addressSchema"}},"required":["makerFee","takerFee","feeRecipientAddress","senderAddress"]},"relayerApiOrderbookResponseSchema":{"type":"object","properties":{"bids":{"$ref":"#/components/schemas/relayerApiOrdersResponseSchema"},"asks":{"$ref":"#/components/schemas/relayerApiOrdersResponseSchema"}},"required":["bids","asks"]},"relayerApiAssetDataPairsResponseSchema":{"type":"object","allOf":[{"$ref":"#/components/schemas/paginatedCollectionSchema"},{"properties":{"records":{"$ref":"#/components/schemas/relayerApiAssetDataPairsSchema"}},"required":["records"]}]},"relayerApiAssetDataTradeInfoSchema":{"type":"object","properties":{"assetData":{"$ref":"#/components/schemas/hexSchema"},"minAmount":{"$ref":"#/components/schemas/numberSchema"},"maxAmount":{"$ref":"#/components/schemas/numberSchema"},"precision":{"type":"number"}},"required":["assetData"]},"relayerApiOrdersChannelSubscribeSchema":{"type":"object","properties":{"type":{"enum":["subscribe"]},"channel":{"enum":["orders"]},"requestId":{"type":"string"},"payload":{"$ref":"#/components/schemas/relayerApiOrdersChannelSubscribePayload"}},"required":["type","channel","requestId"]},"relayerApiOrdersChannelSubscribePayload":{"type":"object","properties":{"makerAssetProxyId":{"$ref":"#/components/schemas/hexSchema"},"takerAssetProxyId":{"$ref":"#/components/schemas/hexSchema"},"networkId":{"type":"number"},"makerAssetAddress":{"$ref":"#/components/schemas/addressSchema"},"takerAssetAddress":{"$ref":"#/components/schemas/addressSchema"},"makerAssetData":{"$ref":"#/components/schemas/hexSchema"},"takerAssetData":{"$ref":"#/components/schemas/hexSchema"},"traderAssetData":{"$ref":"#/components/schemas/hexSchema"}}},"relayerApiOrdersChannelUpdateSchema":{"type":"object","properties":{"type":{"enum":["update"]},"channel":{"enum":["orders"]},"requestId":{"type":"string"},"payload":{"$ref":"#/components/schemas/relayerApiOrdersSchema"}},"required":["type","channel","requestId"]},"relayerApiOrdersResponseSchema":{"type":"object","allOf":[{"$ref":"#/components/schemas/paginatedCollectionSchema"},{"properties":{"records":{"$ref":"#/components/schemas/relayerApiOrdersSchema"}},"required":["records"]}]},"relayerApiAssetDataPairsSchema":{"type":"array","items":{"properties":{"assetDataA":{"$ref":"#/components/schemas/relayerApiAssetDataTradeInfoSchema"},"assetDataB":{"$ref":"#/components/schemas/relayerApiAssetDataTradeInfoSchema"}},"required":["assetDataA","assetDataB"],"type":"object"}}}}}
\ No newline at end of file diff --git a/packages/sra-api/public/index.html b/packages/sra-api/public/index.html new file mode 100644 index 000000000..868047d4f --- /dev/null +++ b/packages/sra-api/public/index.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> + <head> + <title>ReDoc</title> + <!-- needed for adaptive design --> + <meta charset="utf-8"/> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet"> + + <!-- + ReDoc doesn't change outer page styles + --> + <style> + body { + margin: 0; + padding: 0; + } + </style> + </head> + <body> + <redoc spec-url='http://sra-api.s3-website-us-east-1.amazonaws.com/api.json'></redoc> + <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> + </body> +</html>
\ No newline at end of file diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index c2236fda5..4143a663c 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -21,12 +21,12 @@ export const api: OpenApiSpec = { '/v2/asset_pairs': { get: { description: - 'Retrieves a list of available asset pairs and the information required to trade them (in any order). Setting only `asset_data_a` or `asset_data_b` returns pairs filtered by that asset only.', + 'Retrieves a list of available asset pairs and the information required to trade them (in any order). Setting only `assetDataA` or `assetDataB` returns pairs filtered by that asset only.', operationId: 'getAssetPairs', parameters: generateParameters( [ { - name: 'asset_data_a', + name: 'assetDataA', in: 'query', description: 'The assetData value for the first asset in the pair.', example: '0xf47261b04c32345ced77393b3530b1eed0f346429d', @@ -35,7 +35,7 @@ export const api: OpenApiSpec = { }, }, { - name: 'asset_data_b', + name: 'assetDataB', in: 'query', description: 'The assetData value for the second asset in the pair.', example: '0x0257179264389b814a946f3e92105513705ca6b990', @@ -205,7 +205,7 @@ export const api: OpenApiSpec = { }, '/v2/orderbook': { get: { - description: `Retrieves the orderbook for a given asset pair. This endpoint should be [paginated](#section/Pagination). Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted by _taker fee price_ which is defined as the **takerFee** divided by **takerTokenAmount**. After _taker fee price_, orders are to be sorted by expiration in ascending order. The way pagination works for this endpoint is that the **page** and **per_page** query params apply to both \`bids\` and \`asks\` collections, and if \`page\` * \`per_page\` > \`total\` for a certain collection, the \`records\` for that collection should just be empty. `, + description: `Retrieves the orderbook for a given asset pair. This endpoint should be [paginated](#section/Pagination). Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted by _taker fee price_ which is defined as the **takerFee** divided by **takerTokenAmount**. After _taker fee price_, orders are to be sorted by expiration in ascending order. The way pagination works for this endpoint is that the **page** and **perPage** query params apply to both \`bids\` and \`asks\` collections, and if \`page\` * \`perPage\` > \`total\` for a certain collection, the \`records\` for that collection should just be empty. `, operationId: 'getOrderbook', parameters: generateParameters( [ diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index 3e5e84e4c..6f733c9ab 100644 --- a/packages/sra-api/src/md/introduction.md +++ b/packages/sra-api/src/md/introduction.md @@ -6,13 +6,13 @@ Use the [sra-report](https://github.com/0xProject/0x-monorepo/tree/development/p The [JSON schemas](http://json-schema.org/) for the API payloads and responses can be found in [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas). Examples of each payload and response can be found in the library's [test suite](https://github.com/0xProject/0x.js/blob/development/packages/json-schemas/test/schema_test.ts#L1). -``` +```bash npm install @0xproject/json-schemas --save ``` You can easily validate your API's payloads and responses using the [@0xproject/json-schemas](https://github.com/0xProject/0x.js/tree/development/packages/json-schemas) package: -``` +```js import {SchemaValidator, ValidatorResult, schemas} from '@0xproject/json-schemas'; const {relayerApiTokenPairsResponseSchema} = schemas; @@ -26,13 +26,13 @@ const validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, # Pagination -Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example: +Requests that return potentially large collections should respond to the **?page** and **?perPage** parameters. For example: -``` -$ curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=20 +```bash +$ curl https://api.example-relayer.com/v2/asset_pairs?page=3&perPage=20 ``` -Page numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) `per_page` value, the response can return a validation error as specified in the [errors section](#section/Errors). If the query specifies a `page` that does not exist (ie. there are not enough `records`), the response should just return an empty `records` array. +Page numbering should be 1-indexed, not 0-indexed. If a query provides an unreasonable (ie. too high) `perPage` value, the response can return a validation error as specified in the [errors section](#section/Errors). If the query specifies a `page` that does not exist (ie. there are not enough `records`), the response should just return an empty `records` array. All endpoints that are paginated should return a `total`, `page`, `perPage` and a `records` value in the top level of the collection. The value of `total` should be the total number of records for a given query, whereas `records` should be an array representing the response to the query for that page. `page` and `perPage`, are the same values that were specified in the request. See the note in [miscellaneous](#section/Misc.) about formatting `snake_case` vs. `lowerCamelCase`. @@ -42,7 +42,7 @@ These requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/ All requests should be able to specify a **?networkId** query param for all supported networks. For example: -``` +```bash $ curl https://api.example-relayer.com/v2/asset_pairs?networkId=1 ``` @@ -59,7 +59,7 @@ Networks and their Ids: If a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example: -``` +```json { "code": 100, "reason": "Validation failed", @@ -67,7 +67,7 @@ If a certain network is not supported, the response should **400** as specified { "field": "networkId", "code": 1006, - "reason": "Network id 42 is not supported", + "reason": "Network id 42 is not supported" } ] } @@ -78,9 +78,9 @@ If a certain network is not supported, the response should **400** as specified A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a response to provide clients with more context about paging For example: -``` -Link: <https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=20>; rel="next", -<https://api.github.com/user/repos?page=10&per_page=20>; rel="last" +```bash +Link: <https://api.example-relayer.com/v2/asset_pairs?page=3&perPage=20>; rel="next", +<https://api.github.com/user/repos?page=10&perPage=20>; rel="last" ``` This `Link` response header contains one or more Hypermedia link relations. @@ -106,7 +106,7 @@ Rate limit guidance for clients can be optionally returned in the response heade For example: -``` +```bash $ curl -i https://api.example-relayer.com/v2/asset_pairs HTTP/1.1 200 OK Date: Mon, 20 Oct 2017 12:30:06 GMT @@ -136,7 +136,7 @@ Unless the spec defines otherwise, errors to bad requests should respond with HT For all **400** responses, see the [error response schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_error_response_schema.ts#L1). -``` +```json { "code": 101, "reason": "Validation failed", @@ -152,7 +152,7 @@ For all **400** responses, see the [error response schema](https://github.com/0x General error codes: -``` +```bash 100 - Validation Failed 101 - Malformed JSON 102 - Order submission disabled @@ -161,7 +161,7 @@ General error codes: Validation error codes: -``` +```bash 1000 - Required field 1001 - Incorrect format 1002 - Invalid address @@ -177,24 +177,24 @@ As we now support multiple [token transfer proxies](https://github.com/0xProject The identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector). -``` +```js // ERC20 Proxy ID 0xf47261b0 -bytes4(keccak256("ERC20Token(address)")) +bytes4(keccak256('ERC20Token(address)')); // ERC721 Proxy ID 0x08e937fa -bytes4(keccak256("ERC721Token(address,uint256)")) +bytes4(keccak256('ERC721Token(address,uint256)')); ``` Asset data is encoded using [ABI encoding](https://solidity.readthedocs.io/en/develop/abi-spec.html). For example, encoding the ERC20 token contract (address: 0x1dc4c1cefef38a777b15aa20260a54e584b16c48) using the ERC20 Transfer Proxy (id: 0xf47261b0) would be: -``` +```bash 0xf47261b00000000000000000000000001dc4c1cefef38a777b15aa20260a54e584b16c48 ``` Encoding the ERC721 token contract (address: `0x371b13d97f4bf77d724e78c16b7dc74099f40e84`), token id (id: `99`, which hex encoded is `0x63`) and the ERC721 Transfer Proxy (id: 0x08e937fa) would be: -``` +```bash 0x08e937fa000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063 ``` @@ -211,4 +211,4 @@ A good example of such a field is `remainingTakerAssetAmount`, which is a conven * All requests and responses should be of **application/json** content type * All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 token would show up as selling `'1000000000000000000'` units by this API). * All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the `0x` prefix. -* All URL query parameters are to be written in `snake_case` and all queries and responses specified in JSON should use `lowerCamelCase`. +* All parameters are to be written in `lowerCamelCase`. diff --git a/packages/sra-api/src/parameters.ts b/packages/sra-api/src/parameters.ts index 7d63a0a18..10382894c 100644 --- a/packages/sra-api/src/parameters.ts +++ b/packages/sra-api/src/parameters.ts @@ -10,7 +10,7 @@ export const paginationParameters: ParameterObject[] = [ }, }, { - name: 'per_page', + name: 'perPage', in: 'query', description: 'The number of records to return per page.', example: 10, @@ -21,7 +21,7 @@ export const paginationParameters: ParameterObject[] = [ ]; export const networkdIdParameter: ParameterObject = { - name: 'network_id', + name: 'networkId', in: 'query', description: 'The id of the Ethereum network', example: 42, @@ -8994,8 +8994,8 @@ mkdirp@*, mkdirp@0.5.1, mkdirp@0.5.x, mkdirp@0.x.x, "mkdirp@>=0.5 0", mkdirp@^0. minimist "0.0.8" mobx-react@^5.2.3: - version "5.2.3" - resolved "https://registry.npmjs.org/mobx-react/-/mobx-react-5.2.3.tgz#cdf6141c2fe63377c5813cbd254e8ce0d4676631" + version "5.2.5" + resolved "https://registry.npmjs.org/mobx-react/-/mobx-react-5.2.5.tgz#fc44ac17e1798f6b590f064b831d8a1d89850ef0" dependencies: hoist-non-react-statics "^2.5.0" react-lifecycles-compat "^3.0.2" |