diff options
Diffstat (limited to 'packages/sra-api/src/md/introduction.md')
| -rw-r--r-- | packages/sra-api/src/md/introduction.md | 44 |
1 files changed, 22 insertions, 22 deletions
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`. |