From efa67d87aa4f8d9d57883ee85b59f5aaf211eb12 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 26 Jul 2018 14:52:23 -0700 Subject: Rename to sra-api --- packages/sra-api/src/api.ts | 165 ++++++++++++++++++++++++++++++++++++++++++ packages/sra-api/src/index.ts | 1 + 2 files changed, 166 insertions(+) create mode 100644 packages/sra-api/src/api.ts create mode 100644 packages/sra-api/src/index.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts new file mode 100644 index 000000000..9043f6245 --- /dev/null +++ b/packages/sra-api/src/api.ts @@ -0,0 +1,165 @@ +import { OpenApiSpec } from '@loopback/openapi-v3-types'; + +export const api: OpenApiSpec = { + openapi: '3.0.0', + info: { + version: '1.0.0', + title: 'Swagger Petstore', + license: { + name: 'MIT', + }, + }, + servers: [ + { + url: 'http://petstore.swagger.io/v1', + }, + ], + paths: { + '/pets': { + get: { + summary: 'List all pets', + operationId: 'listPets', + tags: ['pets'], + parameters: [ + { + name: 'limit', + in: 'query', + description: 'How many items to return at one time (max 100)', + required: false, + schema: { + type: 'integer', + format: 'int32', + }, + }, + ], + responses: { + '200': { + description: 'An paged array of pets', + headers: { + 'x-next': { + description: 'A link to the next page of responses', + schema: { + type: 'string', + }, + }, + }, + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Pets', + }, + }, + }, + }, + default: { + description: 'unexpected error', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Error', + }, + }, + }, + }, + }, + }, + post: { + summary: 'Create a pet', + operationId: 'createPets', + tags: ['pets'], + responses: { + '201': { + description: 'Null response', + }, + default: { + description: 'unexpected error', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Error', + }, + }, + }, + }, + }, + }, + }, + '/pets/{petId}': { + get: { + summary: 'Info for a specific pet', + operationId: 'showPetById', + tags: ['pets'], + parameters: [ + { + name: 'petId', + in: 'path', + required: true, + description: 'The id of the pet to retrieve', + schema: { + type: 'string', + }, + }, + ], + responses: { + '200': { + description: 'Expected response to a valid request', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Pets', + }, + }, + }, + }, + default: { + description: 'unexpected error', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Error', + }, + }, + }, + }, + }, + }, + }, + }, + components: { + schemas: { + Pet: { + required: ['id', 'name'], + properties: { + id: { + type: 'integer', + format: 'int64', + }, + name: { + type: 'string', + }, + tag: { + type: 'string', + }, + }, + }, + Pets: { + type: 'array', + items: { + $ref: '#/components/schemas/Pet', + }, + }, + Error: { + required: ['code', 'message'], + properties: { + code: { + type: 'integer', + format: 'int32', + }, + message: { + type: 'string', + }, + }, + }, + }, + }, +}; diff --git a/packages/sra-api/src/index.ts b/packages/sra-api/src/index.ts new file mode 100644 index 000000000..4d73f3cd3 --- /dev/null +++ b/packages/sra-api/src/index.ts @@ -0,0 +1 @@ +export { api } from './api'; -- cgit v1.2.3 From 43d7045a5badf61efabffc2844cc6e14fe6f424f Mon Sep 17 00:00:00 2001 From: fragosti Date: Fri, 27 Jul 2018 10:19:20 -0700 Subject: Add scripts --- packages/sra-api/src/api.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 9043f6245..c05311516 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -4,15 +4,14 @@ export const api: OpenApiSpec = { openapi: '3.0.0', info: { version: '1.0.0', - title: 'Swagger Petstore', + title: 'Standard Relayer REST API', license: { - name: 'MIT', + name: 'Apache 2.0', + url: 'https://www.apache.org/licenses/LICENSE-2.0.html', }, }, servers: [ - { - url: 'http://petstore.swagger.io/v1', - }, + // TODO: Use relayer registry information here? ], paths: { '/pets': { -- cgit v1.2.3 From 4aff9515d807feb5fc30431d109d503a6c52f0cd Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 31 Jul 2018 16:37:51 -0700 Subject: Get schema tests running (not crashiing) --- packages/sra-api/src/api.ts | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index c05311516..fd64ab1d7 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -1,3 +1,4 @@ +import { schemas } from '@0xproject/json-schemas'; import { OpenApiSpec } from '@loopback/openapi-v3-types'; export const api: OpenApiSpec = { @@ -14,6 +15,55 @@ export const api: OpenApiSpec = { // TODO: Use relayer registry information here? ], paths: { + '/orders': { + get: { + summary: 'List all pets', + operationId: 'listPets2', + tags: ['pets'], + parameters: [ + { + name: 'limit', + in: 'query', + description: 'How many items to return at one time (max 100)', + required: false, + schema: { + type: 'integer', + format: 'int32', + }, + }, + ], + responses: { + '200': { + description: 'An paged array of pets', + headers: { + 'x-next': { + description: 'A link to the next page of responses', + schema: { + type: 'string', + }, + }, + }, + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Pets', + }, + }, + }, + }, + default: { + description: 'unexpected error', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/Error', + }, + }, + }, + }, + }, + }, + }, '/pets': { get: { summary: 'List all pets', @@ -141,6 +191,7 @@ export const api: OpenApiSpec = { }, }, }, + // Orderbook: schemas.relayerApiOrderBookResponseSchema, Pets: { type: 'array', items: { -- cgit v1.2.3 From 1ce6579c3a05264f93957b0c2d845a1351f4a3b1 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 2 Aug 2018 15:25:40 -0700 Subject: Create asset_pairs SRA endpoint (and establish conventions) --- packages/sra-api/src/api.ts | 226 +++++---------------- packages/sra-api/src/examples/index.ts | 5 + .../relayerApiAssetDataPairsResponseSchema.ts | 21 ++ 3 files changed, 81 insertions(+), 171 deletions(-) create mode 100644 packages/sra-api/src/examples/index.ts create mode 100644 packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index fd64ab1d7..7d2cc6e08 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -1,11 +1,49 @@ import { schemas } from '@0xproject/json-schemas'; import { OpenApiSpec } from '@loopback/openapi-v3-types'; +import { examples } from './examples'; +// We need to replace the `$ref`s to be openAPI compliant. +const openApiSchemas = JSON.parse(JSON.stringify(schemas).replace(/(\/\w+)/g, match => `#/components/schemas${match}`)); + +const paginationParameters = [ + { + name: 'page', + in: 'query', + description: 'The number of the page to request in the collection.', + example: 3, + schema: { + type: 'number', + }, + }, + { + name: 'per_page', + in: 'query', + description: 'The number of records to return per page.', + example: 10, + schema: { + type: 'number', + }, + }, +]; + +const networkdIdParameter = { + name: 'network_id', + in: 'query', + description: 'The id of the Ethereum network', + example: 42, + default: 1, + schema: { + type: 'number', + }, +}; + export const api: OpenApiSpec = { openapi: '3.0.0', info: { version: '1.0.0', title: 'Standard Relayer REST API', + description: + '0x Protocol is an open standard. Because of this, we expect many independent applications to be built that will want to use the protocol. In order to make it easier for anyone to source liquidity that conforms to the 0x order format, relayers can opt-in to implementing a set of standard relayer API endpoints. In doing so, they allow clients of the standard relayer API to access the orders on their orderbook.', license: { name: 'Apache 2.0', url: 'https://www.apache.org/licenses/LICENSE-2.0.html', @@ -15,158 +53,39 @@ export const api: OpenApiSpec = { // TODO: Use relayer registry information here? ], paths: { - '/orders': { + '/asset_pairs': { get: { - summary: 'List all pets', - operationId: 'listPets2', - tags: ['pets'], + 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.', + operationId: 'getAssetPairs', parameters: [ + networkdIdParameter, + ...paginationParameters, { - name: 'limit', + name: 'asset_data_a', in: 'query', - description: 'How many items to return at one time (max 100)', - required: false, + description: 'The assetData value for the first asset in the pair.', + example: '0xf47261b04c32345ced77393b3530b1eed0f346429d', schema: { - type: 'integer', - format: 'int32', - }, - }, - ], - responses: { - '200': { - description: 'An paged array of pets', - headers: { - 'x-next': { - description: 'A link to the next page of responses', - schema: { - type: 'string', - }, - }, - }, - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Pets', - }, - }, - }, - }, - default: { - description: 'unexpected error', - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Error', - }, - }, + $ref: '#/components/schemas/hexSchema', }, }, - }, - }, - }, - '/pets': { - get: { - summary: 'List all pets', - operationId: 'listPets', - tags: ['pets'], - parameters: [ { - name: 'limit', + name: 'asset_data_b', in: 'query', - description: 'How many items to return at one time (max 100)', - required: false, + description: 'The assetData value for the second asset in the pair.', + example: '0x0257179264389b814a946f3e92105513705ca6b990', schema: { - type: 'integer', - format: 'int32', + $ref: '#/components/schemas/hexSchema', }, }, ], responses: { '200': { - description: 'An paged array of pets', - headers: { - 'x-next': { - description: 'A link to the next page of responses', - schema: { - type: 'string', - }, - }, - }, - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Pets', - }, - }, - }, - }, - default: { - description: 'unexpected error', content: { 'application/json': { - schema: { - $ref: '#/components/schemas/Error', - }, - }, - }, - }, - }, - }, - post: { - summary: 'Create a pet', - operationId: 'createPets', - tags: ['pets'], - responses: { - '201': { - description: 'Null response', - }, - default: { - description: 'unexpected error', - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Error', - }, - }, - }, - }, - }, - }, - }, - '/pets/{petId}': { - get: { - summary: 'Info for a specific pet', - operationId: 'showPetById', - tags: ['pets'], - parameters: [ - { - name: 'petId', - in: 'path', - required: true, - description: 'The id of the pet to retrieve', - schema: { - type: 'string', - }, - }, - ], - responses: { - '200': { - description: 'Expected response to a valid request', - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Pets', - }, - }, - }, - }, - default: { - description: 'unexpected error', - content: { - 'application/json': { - schema: { - $ref: '#/components/schemas/Error', - }, + schema: { $ref: '#/components/schemas/relayerApiAssetDataPairsResponseSchema' }, + example: examples.relayerApiAssetDataPairsResponseSchema, }, }, }, @@ -175,41 +94,6 @@ export const api: OpenApiSpec = { }, }, components: { - schemas: { - Pet: { - required: ['id', 'name'], - properties: { - id: { - type: 'integer', - format: 'int64', - }, - name: { - type: 'string', - }, - tag: { - type: 'string', - }, - }, - }, - // Orderbook: schemas.relayerApiOrderBookResponseSchema, - Pets: { - type: 'array', - items: { - $ref: '#/components/schemas/Pet', - }, - }, - Error: { - required: ['code', 'message'], - properties: { - code: { - type: 'integer', - format: 'int32', - }, - message: { - type: 'string', - }, - }, - }, - }, + schemas: openApiSchemas, }, }; diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts new file mode 100644 index 000000000..10ecd182c --- /dev/null +++ b/packages/sra-api/src/examples/index.ts @@ -0,0 +1,5 @@ +import { relayerApiAssetDataPairsResponseSchema } from './relayerApiAssetDataPairsResponseSchema'; + +export const examples = { + relayerApiAssetDataPairsResponseSchema, +}; diff --git a/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts b/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts new file mode 100644 index 000000000..89a0c82fb --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts @@ -0,0 +1,21 @@ +export const relayerApiAssetDataPairsResponseSchema = { + 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', + }, + }, + ], +}; -- cgit v1.2.3 From 36e7cb16aa086892ace18b2c6f3ed5a6e3b26a70 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 2 Aug 2018 18:24:24 -0700 Subject: Add errors and headers --- packages/sra-api/src/api.ts | 48 ++++++++++++++++++++++++++++++++++ packages/sra-api/src/examples/index.ts | 2 ++ 2 files changed, 50 insertions(+) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 7d2cc6e08..2a43e3e8e 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -37,6 +37,51 @@ const networkdIdParameter = { }, }; +const 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', + }, + }, +}; + +const errorResponses = { + '400': { + description: 'Validation error', + content: { + 'application/json': { + schema: { $ref: '#/components/schemas/relayerApiErrorResponseSchema' }, + example: examples.validationError, + }, + }, + }, + '404': { + description: 'Not found', + }, + '429': { + description: 'Too many requests - Rate limit exceeded', + }, + '500': { + description: 'Internal Server Error', + }, + '501': { + description: 'Not implemented.', + }, +}; + export const api: OpenApiSpec = { openapi: '3.0.0', info: { @@ -82,6 +127,8 @@ export const api: OpenApiSpec = { ], responses: { '200': { + headers, + description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/relayerApiAssetDataPairsResponseSchema' }, @@ -89,6 +136,7 @@ export const api: OpenApiSpec = { }, }, }, + ...errorResponses, }, }, }, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index 10ecd182c..eeeb353b3 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,5 +1,7 @@ +import { validationError } from './errors'; import { relayerApiAssetDataPairsResponseSchema } from './relayerApiAssetDataPairsResponseSchema'; export const examples = { + validationError, relayerApiAssetDataPairsResponseSchema, }; -- cgit v1.2.3 From 260640feed5dcda52936873397cf3b2c899718c6 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 2 Aug 2018 18:39:52 -0700 Subject: Refactor using some utility methods --- packages/sra-api/src/api.ts | 135 ++++++-------------------------- packages/sra-api/src/errors.ts | 24 ++++++ packages/sra-api/src/examples/errors.ts | 11 +++ packages/sra-api/src/headers.ts | 20 +++++ packages/sra-api/src/parameters.ts | 37 +++++++++ packages/sra-api/src/responses.ts | 17 ++++ 6 files changed, 135 insertions(+), 109 deletions(-) create mode 100644 packages/sra-api/src/errors.ts create mode 100644 packages/sra-api/src/examples/errors.ts create mode 100644 packages/sra-api/src/headers.ts create mode 100644 packages/sra-api/src/parameters.ts create mode 100644 packages/sra-api/src/responses.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 2a43e3e8e..33d4d3619 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -2,86 +2,11 @@ import { schemas } from '@0xproject/json-schemas'; import { OpenApiSpec } from '@loopback/openapi-v3-types'; import { examples } from './examples'; +import { generateParameters } from './parameters'; +import { generateResponses } from './responses'; // We need to replace the `$ref`s to be openAPI compliant. const openApiSchemas = JSON.parse(JSON.stringify(schemas).replace(/(\/\w+)/g, match => `#/components/schemas${match}`)); -const paginationParameters = [ - { - name: 'page', - in: 'query', - description: 'The number of the page to request in the collection.', - example: 3, - schema: { - type: 'number', - }, - }, - { - name: 'per_page', - in: 'query', - description: 'The number of records to return per page.', - example: 10, - schema: { - type: 'number', - }, - }, -]; - -const networkdIdParameter = { - name: 'network_id', - in: 'query', - description: 'The id of the Ethereum network', - example: 42, - default: 1, - schema: { - type: 'number', - }, -}; - -const 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', - }, - }, -}; - -const errorResponses = { - '400': { - description: 'Validation error', - content: { - 'application/json': { - schema: { $ref: '#/components/schemas/relayerApiErrorResponseSchema' }, - example: examples.validationError, - }, - }, - }, - '404': { - description: 'Not found', - }, - '429': { - description: 'Too many requests - Rate limit exceeded', - }, - '500': { - description: 'Internal Server Error', - }, - '501': { - description: 'Not implemented.', - }, -}; - export const api: OpenApiSpec = { openapi: '3.0.0', info: { @@ -103,41 +28,33 @@ export const api: OpenApiSpec = { 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.', operationId: 'getAssetPairs', - parameters: [ - networkdIdParameter, - ...paginationParameters, - { - name: 'asset_data_a', - in: 'query', - description: 'The assetData value for the first asset in the pair.', - example: '0xf47261b04c32345ced77393b3530b1eed0f346429d', - schema: { - $ref: '#/components/schemas/hexSchema', - }, - }, - { - name: 'asset_data_b', - in: 'query', - description: 'The assetData value for the second asset in the pair.', - example: '0x0257179264389b814a946f3e92105513705ca6b990', - schema: { - $ref: '#/components/schemas/hexSchema', + parameters: generateParameters( + [ + { + name: 'asset_data_a', + in: 'query', + description: 'The assetData value for the first asset in the pair.', + example: '0xf47261b04c32345ced77393b3530b1eed0f346429d', + schema: { + $ref: '#/components/schemas/hexSchema', + }, }, - }, - ], - responses: { - '200': { - headers, - description: 'OK', - content: { - 'application/json': { - schema: { $ref: '#/components/schemas/relayerApiAssetDataPairsResponseSchema' }, - example: examples.relayerApiAssetDataPairsResponseSchema, + { + name: 'asset_data_b', + in: 'query', + description: 'The assetData value for the second asset in the pair.', + example: '0x0257179264389b814a946f3e92105513705ca6b990', + schema: { + $ref: '#/components/schemas/hexSchema', }, }, - }, - ...errorResponses, - }, + ], + true, + ), + responses: generateResponses( + 'relayerApiAssetDataPairsResponseSchema', + examples.relayerApiAssetDataPairsResponseSchema, + ), }, }, }, diff --git a/packages/sra-api/src/errors.ts b/packages/sra-api/src/errors.ts new file mode 100644 index 000000000..20c35514f --- /dev/null +++ b/packages/sra-api/src/errors.ts @@ -0,0 +1,24 @@ +import { examples } from './examples'; +export const errorResponses = { + '400': { + description: 'Validation error', + content: { + 'application/json': { + schema: { $ref: '#/components/schemas/relayerApiErrorResponseSchema' }, + example: examples.validationError, + }, + }, + }, + '404': { + description: 'Not found', + }, + '429': { + description: 'Too many requests - Rate limit exceeded', + }, + '500': { + description: 'Internal Server Error', + }, + '501': { + description: 'Not implemented.', + }, +}; diff --git a/packages/sra-api/src/examples/errors.ts b/packages/sra-api/src/examples/errors.ts new file mode 100644 index 000000000..81f29d81c --- /dev/null +++ b/packages/sra-api/src/examples/errors.ts @@ -0,0 +1,11 @@ +export const validationError = { + code: 100, + reason: 'Validation failed', + validationErrors: [ + { + field: 'networkId', + code: 1006, + reason: 'Network id 42 is not supported', + }, + ], +}; diff --git a/packages/sra-api/src/headers.ts b/packages/sra-api/src/headers.ts new file mode 100644 index 000000000..152254c9f --- /dev/null +++ b/packages/sra-api/src/headers.ts @@ -0,0 +1,20 @@ +export const 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', + }, + }, +}; diff --git a/packages/sra-api/src/parameters.ts b/packages/sra-api/src/parameters.ts new file mode 100644 index 000000000..dac898931 --- /dev/null +++ b/packages/sra-api/src/parameters.ts @@ -0,0 +1,37 @@ +import { ParameterLocation, ParameterObject } from '@loopback/openapi-v3-types'; +export const paginationParameters: ParameterObject[] = [ + { + name: 'page', + in: 'query', + description: 'The number of the page to request in the collection.', + example: 3, + schema: { + type: 'number', + }, + }, + { + name: 'per_page', + in: 'query', + description: 'The number of records to return per page.', + example: 10, + schema: { + type: 'number', + }, + }, +]; + +export const networkdIdParameter = { + name: 'network_id', + in: 'query', + description: 'The id of the Ethereum network', + example: 42, + default: 1, + schema: { + type: 'number', + }, +}; + +export const generateParameters = (parameters: ParameterObject[], isPaginated: boolean = false): ParameterObject[] => { + const optionalParameters = isPaginated ? paginationParameters : []; + return [...optionalParameters, ...parameters]; +}; diff --git a/packages/sra-api/src/responses.ts b/packages/sra-api/src/responses.ts new file mode 100644 index 000000000..59c679b9c --- /dev/null +++ b/packages/sra-api/src/responses.ts @@ -0,0 +1,17 @@ +import { ResponsesObject } from '@loopback/openapi-v3-types'; + +import { errorResponses } from './errors'; +import { headers } from './headers'; + +export const generateResponses = (schemaName: string, example: any): ResponsesObject => ({ + '200': { + headers, + description: 'OK', + content: { + 'application/json': { + schema: { $ref: `#/components/schemas/${schemaName}` }, + }, + }, + }, + ...errorResponses, +}); -- cgit v1.2.3 From be472b61e776ea44a872b54742af8664660aa27c Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 13:22:11 -0700 Subject: Add markdown section --- packages/sra-api/src/api.ts | 6 +- packages/sra-api/src/md/index.ts | 5 + packages/sra-api/src/md/introduction.md | 180 ++++++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+), 3 deletions(-) create mode 100644 packages/sra-api/src/md/index.ts create mode 100644 packages/sra-api/src/md/introduction.md (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 33d4d3619..da61cb1b0 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -2,6 +2,7 @@ import { schemas } from '@0xproject/json-schemas'; import { OpenApiSpec } from '@loopback/openapi-v3-types'; import { examples } from './examples'; +import { md } from './md'; import { generateParameters } from './parameters'; import { generateResponses } from './responses'; // We need to replace the `$ref`s to be openAPI compliant. @@ -10,10 +11,9 @@ const openApiSchemas = JSON.parse(JSON.stringify(schemas).replace(/(\/\w+)/g, ma export const api: OpenApiSpec = { openapi: '3.0.0', info: { - version: '1.0.0', + version: '2.0.0', title: 'Standard Relayer REST API', - description: - '0x Protocol is an open standard. Because of this, we expect many independent applications to be built that will want to use the protocol. In order to make it easier for anyone to source liquidity that conforms to the 0x order format, relayers can opt-in to implementing a set of standard relayer API endpoints. In doing so, they allow clients of the standard relayer API to access the orders on their orderbook.', + description: md.introduction, license: { name: 'Apache 2.0', url: 'https://www.apache.org/licenses/LICENSE-2.0.html', diff --git a/packages/sra-api/src/md/index.ts b/packages/sra-api/src/md/index.ts new file mode 100644 index 000000000..076c3c45c --- /dev/null +++ b/packages/sra-api/src/md/index.ts @@ -0,0 +1,5 @@ +import { readFileSync } from 'fs'; + +export const md = { + introduction: readFileSync('src/md/introduction.md').toString(), +}; diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md new file mode 100644 index 000000000..c3aa4d4da --- /dev/null +++ b/packages/sra-api/src/md/introduction.md @@ -0,0 +1,180 @@ +# Pagination + +Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example: + +``` +curl https://api.example-relayer.com/v2/token_pairs?page=3&per_page=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](#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](#misc) about formatting `snake_case` vs. `lowerCamelCase`. + +These requests include the [`asset_pairs`](#get-v2-asset-pairs), [`orders`](#get-v2-orders), and [`orderbook`](#get-v2-orderbook) endpoints. + +# Network Id +All requests should be able to specify a **?networkId** query param for all supported networks. For example: +``` +curl https://api.example-relayer.com/v2/token_pairs?networkId=1 +``` +If the query param is not provided, it should default to **1** (mainnet). + +Networks and their Ids: + +| Network Id | Network Name | +| ---------- | ------------ | +| 1 | Mainnet | +| 42 | Kovan | +| 3 | Ropsten | +| 4 | Rinkeby | + + If a certain network is not supported, the response should **400** as specified in the [error response](#error-response) section. For example: + +``` +{ + "code": 100, + "reason": "Validation failed", + "validationErrors": [ + { + "field": "networkId", + "code": 1006, + "reason": "Network id 42 is not supported", + } + ] +} +``` + +# Link Header + +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: ; rel="next", +; rel="last" +``` + +This `Link` response header contains one or more Hypermedia link relations. + +The possible `rel` values are: + +| Name | Description | +| ----- | ------------------------------------------------------------- | +| next | The link relation for the immediate next page of results. | +| last | The link relation for the last page of results. | +| first | The link relation for the first page of results. | +| prev | The link relation for the immediate previous page of results. | + +# Rate Limits + +Rate limit guidance for clients can be optionally returned in the response headers: + +| Header Name | Description | +| --------------------- | ---------------------------------------------------------------------------- | +| X-RateLimit-Limit | The maximum number of requests you're permitted to make per hour. | +| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. | +| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. | + +For example: + +``` +curl -i https://api.example-relayer.com/v2/token_pairs +HTTP/1.1 200 OK +Date: Mon, 20 Oct 2017 12:30:06 GMT +Status: 200 OK +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 56 +X-RateLimit-Reset: 1372700873 +``` +When a rate limit is exceeded, a status of **429 Too Many Requests** should be returned. + +# Errors + +Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes. + +## Common error codes + +| Code | Reason | +| ---- | --------------------------------------- | +| 400 | Bad Request – Invalid request format | +| 404 | Not found | +| 429 | Too many requests - Rate limit exceeded | +| 500 | Internal Server Error | +| 501 | Not Implemented | + +## Error reporting format +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). + +``` +{ + "code": 101, + "reason": "Validation failed", + "validationErrors": [ + { + "field": "maker", + "code": 1002, + "reason": "Invalid address" + } + ] +} +``` + +General error codes: + +``` +100 - Validation Failed +101 - Malformed JSON +102 - Order submission disabled +103 - Throttled +``` + +Validation error codes: + +``` +1000 - Required field +1001 - Incorrect format +1002 - Invalid address +1003 - Address not supported +1004 - Value out of range +1005 - Invalid signature or hash +1006 - Unsupported option +``` + +# Asset Data Encoding + +As 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). + +The identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector). +``` +// ERC20 Proxy ID 0xf47261b0 +bytes4(keccak256("ERC20Token(address)")) +// ERC721 Proxy ID 0x08e937fa +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: +``` +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: +``` +0x08e937fa000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063 +``` + +For 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). + +# Meta Data in Order Responses + +In 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. + +A 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). + +# Misc. + +* 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`. -- cgit v1.2.3 From 3b542bf356f14e7bfd5bbd740d2df55ff64e1309 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 13:36:59 -0700 Subject: Add static site build --- packages/sra-api/src/api.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index da61cb1b0..762d3f4d6 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -19,11 +19,8 @@ export const api: OpenApiSpec = { url: 'https://www.apache.org/licenses/LICENSE-2.0.html', }, }, - servers: [ - // TODO: Use relayer registry information here? - ], paths: { - '/asset_pairs': { + '/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.', -- cgit v1.2.3 From f4c2fabbf8f8eccd5cd7c65035e78ad268a34b57 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 15:03:52 -0700 Subject: Minor refactoring --- packages/sra-api/src/api.ts | 3 ++- packages/sra-api/src/examples/index.ts | 4 ++-- .../relayerApiAssetDataPairsResponseSchema.ts | 21 --------------------- packages/sra-api/src/responses.ts | 5 +++-- 4 files changed, 7 insertions(+), 26 deletions(-) delete mode 100644 packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 762d3f4d6..c93d57946 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -50,7 +50,8 @@ export const api: OpenApiSpec = { ), responses: generateResponses( 'relayerApiAssetDataPairsResponseSchema', - examples.relayerApiAssetDataPairsResponseSchema, + examples.relayerApiAssetDataPairsResponse, + `Returns a collection of available asset pairs with some meta info`, ), }, }, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index eeeb353b3..a9d08691e 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,7 +1,7 @@ import { validationError } from './errors'; -import { relayerApiAssetDataPairsResponseSchema } from './relayerApiAssetDataPairsResponseSchema'; +import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; export const examples = { validationError, - relayerApiAssetDataPairsResponseSchema, + relayerApiAssetDataPairsResponse, }; diff --git a/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts b/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts deleted file mode 100644 index 89a0c82fb..000000000 --- a/packages/sra-api/src/examples/relayerApiAssetDataPairsResponseSchema.ts +++ /dev/null @@ -1,21 +0,0 @@ -export const relayerApiAssetDataPairsResponseSchema = { - 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', - }, - }, - ], -}; diff --git a/packages/sra-api/src/responses.ts b/packages/sra-api/src/responses.ts index 59c679b9c..03a0cced8 100644 --- a/packages/sra-api/src/responses.ts +++ b/packages/sra-api/src/responses.ts @@ -3,13 +3,14 @@ import { ResponsesObject } from '@loopback/openapi-v3-types'; import { errorResponses } from './errors'; import { headers } from './headers'; -export const generateResponses = (schemaName: string, example: any): ResponsesObject => ({ +export const generateResponses = (schemaName: string, example: any, description: string = 'OK'): ResponsesObject => ({ '200': { headers, - description: 'OK', + description, content: { 'application/json': { schema: { $ref: `#/components/schemas/${schemaName}` }, + example, }, }, }, -- cgit v1.2.3 From f36a43a83f6c8ae32d36768da8c97858ef051446 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 15:38:50 -0700 Subject: Add orders endpoint --- packages/sra-api/src/api.ts | 127 ++++++++++++++++++++- packages/sra-api/src/examples/index.ts | 2 + .../examples/relayerApiAssetDataPairsResponse.ts | 21 ++++ .../src/examples/relayerApiOrdersResponse.ts | 26 +++++ 4 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 packages/sra-api/src/examples/relayerApiAssetDataPairsResponse.ts create mode 100644 packages/sra-api/src/examples/relayerApiOrdersResponse.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index c93d57946..d80fb9b41 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -5,7 +5,7 @@ import { examples } from './examples'; import { md } from './md'; import { generateParameters } from './parameters'; import { generateResponses } from './responses'; -// We need to replace the `$ref`s to be openAPI compliant. +// We need to replace the `$ref`s to be OpenAPI compliant. const openApiSchemas = JSON.parse(JSON.stringify(schemas).replace(/(\/\w+)/g, match => `#/components/schemas${match}`)); export const api: OpenApiSpec = { @@ -55,6 +55,131 @@ export const api: OpenApiSpec = { ), }, }, + '/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: generateParameters( + [ + { + 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', + }, + }, + ], + true, + ), + responses: generateResponses( + 'relayerApiOrdersResponseSchema', + examples.relayerApiOrdersResponse, + `Returns a collection of 0x orders with meta-data as specified by query params`, + ), + }, + }, }, components: { schemas: openApiSchemas, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index a9d08691e..0ae8a22a7 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,7 +1,9 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; +import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; export const examples = { validationError, relayerApiAssetDataPairsResponse, + relayerApiOrdersResponse, }; diff --git a/packages/sra-api/src/examples/relayerApiAssetDataPairsResponse.ts b/packages/sra-api/src/examples/relayerApiAssetDataPairsResponse.ts new file mode 100644 index 000000000..9eead5239 --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiAssetDataPairsResponse.ts @@ -0,0 +1,21 @@ +export const relayerApiAssetDataPairsResponse = { + 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', + }, + }, + ], +}; diff --git a/packages/sra-api/src/examples/relayerApiOrdersResponse.ts b/packages/sra-api/src/examples/relayerApiOrdersResponse.ts new file mode 100644 index 000000000..ac16e7e34 --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrdersResponse.ts @@ -0,0 +1,26 @@ +export const relayerApiOrdersResponse = { + 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: {}, + }, + ], +}; -- cgit v1.2.3 From f6dbc239958e37a585d3f89b98eb6cd473895335 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 16:10:59 -0700 Subject: Add GET order endpoint spec --- packages/sra-api/src/api.ts | 27 +++++++++++++++++++++++- packages/sra-api/src/examples/index.ts | 2 ++ packages/sra-api/src/examples/relayerApiOrder.ts | 19 +++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 packages/sra-api/src/examples/relayerApiOrder.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index d80fb9b41..2cc15b297 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -176,7 +176,32 @@ export const api: OpenApiSpec = { responses: generateResponses( 'relayerApiOrdersResponseSchema', examples.relayerApiOrdersResponse, - `Returns a collection of 0x orders with meta-data as specified by query params`, + `A collection of 0x orders with meta-data as specified by query params`, + ), + }, + }, + '/v2/order/{orderHash}': { + get: { + description: 'Retrieves the 0x order with meta info that is associated with the hash.', + operationId: 'getOrder', + parameters: generateParameters( + [ + { + name: 'orderHash', + in: 'path', + description: 'The hash of the desired 0x order.', + example: '0xd4b103c42d2512eef3fee775e097f044291615d25f5d71e0ac70dbd49d223591', + schema: { + $ref: '#/components/schemas/orderHashSchema', + }, + }, + ], + true, + ), + responses: generateResponses( + 'relayerApiOrderSchema', + examples.relayerApiOrder, + `The order and meta info associated with the orderHash`, ), }, }, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index 0ae8a22a7..d99c0469b 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,9 +1,11 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; +import { relayerApiOrder } from './relayerApiOrder'; import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; export const examples = { validationError, relayerApiAssetDataPairsResponse, + relayerApiOrder, relayerApiOrdersResponse, }; diff --git a/packages/sra-api/src/examples/relayerApiOrder.ts b/packages/sra-api/src/examples/relayerApiOrder.ts new file mode 100644 index 000000000..31181d677 --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrder.ts @@ -0,0 +1,19 @@ +export const relayerApiOrder = { + 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: {}, +}; -- cgit v1.2.3 From 3771df728c2dfcdeeb3fc49cd27ef864f2e94316 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 16:24:31 -0700 Subject: Add GET OrderBook endpoint --- packages/sra-api/src/api.ts | 36 +++++++++++++++ packages/sra-api/src/examples/index.ts | 2 + .../src/examples/relayerApiOrderBookResponse.ts | 54 ++++++++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 packages/sra-api/src/examples/relayerApiOrderBookResponse.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 2cc15b297..5289a31f3 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -205,6 +205,42 @@ 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. `, + operationId: 'getOrderBook', + parameters: generateParameters( + [ + { + 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', + }, + }, + ], + true, + ), + responses: generateResponses( + 'relayerApiOrderBookResponseSchema', + examples.relayerApiOrderBookResponse, + `The sorted order book for the specified asset pair.`, + ), + }, + }, }, components: { schemas: openApiSchemas, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index d99c0469b..51d979fe4 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,11 +1,13 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; import { relayerApiOrder } from './relayerApiOrder'; +import { relayerApiOrderBookResponse } from './relayerApiOrderBookResponse'; import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; export const examples = { validationError, relayerApiAssetDataPairsResponse, relayerApiOrder, + relayerApiOrderBookResponse, relayerApiOrdersResponse, }; diff --git a/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts b/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts new file mode 100644 index 000000000..4e1e7a8eb --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts @@ -0,0 +1,54 @@ +export const relayerApiOrderBookResponse = { + 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: {}, + }, + ], + }, +}; -- cgit v1.2.3 From e6c91493f2f99dea2e7e0ef6aa1365552f100fa4 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 16:26:25 -0700 Subject: token_pairs -> asset_pairs --- packages/sra-api/src/md/introduction.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index c3aa4d4da..4d0679f9e 100644 --- a/packages/sra-api/src/md/introduction.md +++ b/packages/sra-api/src/md/introduction.md @@ -3,7 +3,7 @@ Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example: ``` -curl https://api.example-relayer.com/v2/token_pairs?page=3&per_page=20 +curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=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](#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. @@ -15,7 +15,7 @@ These requests include the [`asset_pairs`](#get-v2-asset-pairs), [`orders`](#get # Network Id All requests should be able to specify a **?networkId** query param for all supported networks. For example: ``` -curl https://api.example-relayer.com/v2/token_pairs?networkId=1 +curl https://api.example-relayer.com/v2/asset_pairs?networkId=1 ``` If the query param is not provided, it should default to **1** (mainnet). @@ -50,7 +50,7 @@ A [Link Header](https://tools.ietf.org/html/rfc5988) can be included in a respon For example: ``` -Link: ; rel="next", +Link: ; rel="next", ; rel="last" ``` @@ -78,7 +78,7 @@ Rate limit guidance for clients can be optionally returned in the response heade For example: ``` -curl -i https://api.example-relayer.com/v2/token_pairs +curl -i https://api.example-relayer.com/v2/asset_pairs HTTP/1.1 200 OK Date: Mon, 20 Oct 2017 12:30:06 GMT Status: 200 OK -- cgit v1.2.3 From b0a7db81cb2bde774f410938578476200d1dc694 Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 16:51:47 -0700 Subject: Add GET order_config --- packages/sra-api/src/api.ts | 23 ++++++++++++++++++++++ packages/sra-api/src/examples/index.ts | 4 ++++ .../sra-api/src/examples/relayerApiOrderConfig | 0 .../src/examples/relayerApiOrderConfigPayload.ts | 10 ++++++++++ .../src/examples/relayerApiOrderConfigResponse.ts | 6 ++++++ 5 files changed, 43 insertions(+) create mode 100644 packages/sra-api/src/examples/relayerApiOrderConfig create mode 100644 packages/sra-api/src/examples/relayerApiOrderConfigPayload.ts create mode 100644 packages/sra-api/src/examples/relayerApiOrderConfigResponse.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 5289a31f3..129fd3722 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -241,6 +241,29 @@ export const api: OpenApiSpec = { ), }, }, + '/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', + 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: examples.relayerApiOrderConfigPayload, + }, + }, + }, + responses: generateResponses( + 'relayerApiOrderConfigResponseSchema', + examples.relayerApiOrderConfigResponse, + `The additional fields necessary in order to submit an order to the relayer.`, + ), + }, + }, }, components: { schemas: openApiSchemas, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index 51d979fe4..6581b840f 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -2,6 +2,8 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; import { relayerApiOrder } from './relayerApiOrder'; import { relayerApiOrderBookResponse } from './relayerApiOrderBookResponse'; +import { relayerApiOrderConfigPayload } from './relayerApiOrderConfigPayload'; +import { relayerApiOrderConfigResponse } from './relayerApiOrderConfigResponse'; import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; export const examples = { @@ -9,5 +11,7 @@ export const examples = { relayerApiAssetDataPairsResponse, relayerApiOrder, relayerApiOrderBookResponse, + relayerApiOrderConfigPayload, + relayerApiOrderConfigResponse, relayerApiOrdersResponse, }; diff --git a/packages/sra-api/src/examples/relayerApiOrderConfig b/packages/sra-api/src/examples/relayerApiOrderConfig new file mode 100644 index 000000000..e69de29bb diff --git a/packages/sra-api/src/examples/relayerApiOrderConfigPayload.ts b/packages/sra-api/src/examples/relayerApiOrderConfigPayload.ts new file mode 100644 index 000000000..5251d5b4d --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrderConfigPayload.ts @@ -0,0 +1,10 @@ +export const relayerApiOrderConfigPayload = { + makerAddress: '0x9e56625509c2f60af937f23b7b532600390e8c8b', + takerAddress: '0xa2b31dacf30a9c50ca473337c01d8a201ae33e32', + makerAssetAmount: '10000000000000000', + takerAssetAmount: '20000000000000000', + makerAssetData: '0xf47261b04c32345ced77393b3530b1eed0f346429d', + takerAssetData: '0x0257179264389b814a946f3e92105513705ca6b990', + exchangeAddress: '0x12459c951127e0c374ff9105dda097662a027093', + expirationTimeSeconds: '1532560590', +}; diff --git a/packages/sra-api/src/examples/relayerApiOrderConfigResponse.ts b/packages/sra-api/src/examples/relayerApiOrderConfigResponse.ts new file mode 100644 index 000000000..a3c531c0a --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrderConfigResponse.ts @@ -0,0 +1,6 @@ +export const relayerApiOrderConfigResponse = { + senderAddress: '0xa2b31dacf30a9c50ca473337c01d8a201ae33e32', + feeRecipientAddress: '0xb046140686d052fff581f63f8136cce132e857da', + makerFee: '100000000000000', + takerFee: '200000000000000', +}; -- cgit v1.2.3 From 95b656f360f635447725e00bb90642f1b859477a Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 17:42:22 -0700 Subject: Add GET fee_recipients --- packages/sra-api/src/api.ts | 12 ++++++++++++ packages/sra-api/src/examples/index.ts | 2 ++ .../sra-api/src/examples/relayerApiFeeRecipientsResponse.ts | 10 ++++++++++ 3 files changed, 24 insertions(+) create mode 100644 packages/sra-api/src/examples/relayerApiFeeRecipientsResponse.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 129fd3722..50e656599 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -264,6 +264,18 @@ export const api: OpenApiSpec = { ), }, }, + '/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: generateParameters([], true), + responses: generateResponses( + 'relayerApiFeeRecipientsResponseSchema', + examples.relayerApiFeeRecipientsResponse, + `A collection of all used fee recipient addresses.`, + ), + }, + }, }, components: { schemas: openApiSchemas, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index 6581b840f..06560f8ad 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -1,5 +1,6 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; +import { relayerApiFeeRecipientsResponse } from './relayerApiFeeRecipientsResponse'; import { relayerApiOrder } from './relayerApiOrder'; import { relayerApiOrderBookResponse } from './relayerApiOrderBookResponse'; import { relayerApiOrderConfigPayload } from './relayerApiOrderConfigPayload'; @@ -9,6 +10,7 @@ import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; export const examples = { validationError, relayerApiAssetDataPairsResponse, + relayerApiFeeRecipientsResponse, relayerApiOrder, relayerApiOrderBookResponse, relayerApiOrderConfigPayload, diff --git a/packages/sra-api/src/examples/relayerApiFeeRecipientsResponse.ts b/packages/sra-api/src/examples/relayerApiFeeRecipientsResponse.ts new file mode 100644 index 000000000..0182af629 --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiFeeRecipientsResponse.ts @@ -0,0 +1,10 @@ +export const relayerApiFeeRecipientsResponse = { + total: 3, + page: 1, + perPage: 10, + records: [ + '0x6eC92694ea172ebC430C30fa31De87620967A082', + '0x9e56625509c2f60af937f23b7b532600390e8c8b', + '0xa2b31dacf30a9c50ca473337c01d8a201ae33e32', + ], +}; -- cgit v1.2.3 From 4e30bc3e16d7e0e8876fab09a61e9446c2c9d93f Mon Sep 17 00:00:00 2001 From: fragosti Date: Tue, 7 Aug 2018 17:58:38 -0700 Subject: Add POST order endpoint --- packages/sra-api/src/api.ts | 22 +++++++++++++++++++++- packages/sra-api/src/examples/index.ts | 2 ++ packages/sra-api/src/examples/signedOrder.ts | 16 ++++++++++++++++ packages/sra-api/src/parameters.ts | 4 ++-- packages/sra-api/src/responses.ts | 24 +++++++++++++++--------- 5 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 packages/sra-api/src/examples/signedOrder.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 50e656599..5973e11cd 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -196,7 +196,7 @@ export const api: OpenApiSpec = { }, }, ], - true, + false, ), responses: generateResponses( 'relayerApiOrderSchema', @@ -245,6 +245,7 @@ export const api: OpenApiSpec = { 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: generateParameters([], false), requestBody: { description: 'The fields of a 0x order the relayer may want to decide what configuration to send back.', @@ -276,6 +277,25 @@ export const api: OpenApiSpec = { ), }, }, + '/v2/order': { + post: { + description: `Submit a signed order to the relayer.`, + operationId: 'postOrder', + parameters: generateParameters([], false), + requestBody: { + description: 'A valid signed 0x order based on the schema.', + content: { + 'application/json': { + schema: { + $ref: '#/components/schemas/signedOrderSchema', + }, + example: examples.signedOrder, + }, + }, + }, + responses: generateResponses(), + }, + }, }, components: { schemas: openApiSchemas, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index 06560f8ad..cdc4fac53 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -6,6 +6,7 @@ import { relayerApiOrderBookResponse } from './relayerApiOrderBookResponse'; import { relayerApiOrderConfigPayload } from './relayerApiOrderConfigPayload'; import { relayerApiOrderConfigResponse } from './relayerApiOrderConfigResponse'; import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; +import { signedOrder } from './signedOrder'; export const examples = { validationError, @@ -16,4 +17,5 @@ export const examples = { relayerApiOrderConfigPayload, relayerApiOrderConfigResponse, relayerApiOrdersResponse, + signedOrder, }; diff --git a/packages/sra-api/src/examples/signedOrder.ts b/packages/sra-api/src/examples/signedOrder.ts new file mode 100644 index 000000000..440566027 --- /dev/null +++ b/packages/sra-api/src/examples/signedOrder.ts @@ -0,0 +1,16 @@ +export const signedOrder = { + 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', +}; diff --git a/packages/sra-api/src/parameters.ts b/packages/sra-api/src/parameters.ts index dac898931..bfa261df0 100644 --- a/packages/sra-api/src/parameters.ts +++ b/packages/sra-api/src/parameters.ts @@ -20,7 +20,7 @@ export const paginationParameters: ParameterObject[] = [ }, ]; -export const networkdIdParameter = { +export const networkdIdParameter: ParameterObject = { name: 'network_id', in: 'query', description: 'The id of the Ethereum network', @@ -33,5 +33,5 @@ export const networkdIdParameter = { export const generateParameters = (parameters: ParameterObject[], isPaginated: boolean = false): ParameterObject[] => { const optionalParameters = isPaginated ? paginationParameters : []; - return [...optionalParameters, ...parameters]; + return [networkdIdParameter, ...optionalParameters, ...parameters]; }; diff --git a/packages/sra-api/src/responses.ts b/packages/sra-api/src/responses.ts index 03a0cced8..cd7352058 100644 --- a/packages/sra-api/src/responses.ts +++ b/packages/sra-api/src/responses.ts @@ -3,16 +3,22 @@ import { ResponsesObject } from '@loopback/openapi-v3-types'; import { errorResponses } from './errors'; import { headers } from './headers'; -export const generateResponses = (schemaName: string, example: any, description: string = 'OK'): ResponsesObject => ({ - '200': { - headers, - description, - content: { +export const generateResponses = (schemaName?: string, example?: any, description: string = 'OK'): ResponsesObject => { + const responses = { + '200': { + headers, + description, + content: {}, + }, + ...errorResponses, + }; + if (schemaName) { + responses['200'].content = { 'application/json': { schema: { $ref: `#/components/schemas/${schemaName}` }, example, }, - }, - }, - ...errorResponses, -}); + }; + } + return responses; +}; -- cgit v1.2.3 From 9aacceb0e4549a7a72cae7cbf74ea819db184d80 Mon Sep 17 00:00:00 2001 From: fragosti Date: Wed, 8 Aug 2018 14:00:50 -0700 Subject: Remove tests directory, use swagger api, make json api compliant --- packages/sra-api/src/api.ts | 6 ++-- packages/sra-api/src/json-schemas.ts | 63 ++++++++++++++++++++++++++++++++++++ packages/sra-api/src/parameters.ts | 1 - 3 files changed, 65 insertions(+), 5 deletions(-) create mode 100644 packages/sra-api/src/json-schemas.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index 5973e11cd..e578ddc74 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -1,12 +1,10 @@ -import { schemas } from '@0xproject/json-schemas'; import { OpenApiSpec } from '@loopback/openapi-v3-types'; import { examples } from './examples'; +import { schemas } from './json-schemas'; import { md } from './md'; import { generateParameters } from './parameters'; import { generateResponses } from './responses'; -// We need to replace the `$ref`s to be OpenAPI compliant. -const openApiSchemas = JSON.parse(JSON.stringify(schemas).replace(/(\/\w+)/g, match => `#/components/schemas${match}`)); export const api: OpenApiSpec = { openapi: '3.0.0', @@ -298,6 +296,6 @@ export const api: OpenApiSpec = { }, }, components: { - schemas: openApiSchemas, + schemas, }, }; diff --git a/packages/sra-api/src/json-schemas.ts b/packages/sra-api/src/json-schemas.ts new file mode 100644 index 000000000..5b222a43f --- /dev/null +++ b/packages/sra-api/src/json-schemas.ts @@ -0,0 +1,63 @@ +import { schemas as jsonSchemas } from '@0xproject/json-schemas'; + +// Only include schemas we actually need +const { + numberSchema, + addressSchema, + hexSchema, + orderHashSchema, + orderSchema, + signedOrderSchema, + signedOrdersSchema, + ordersSchema, + paginatedCollectionSchema, + relayerApiErrorResponseSchema, + relayerApiFeeRecipientsResponseSchema, + relayerApiOrderSchema, + relayerApiOrdersSchema, + relayerApiOrderConfigPayloadSchema, + relayerApiOrderConfigResponseSchema, + relayerApiOrderBookResponseSchema, + relayerApiAssetDataPairsResponseSchema, + relayerApiAssetDataTradeInfoSchema, + relayerApiOrdersChannelSubscribeSchema, + relayerApiOrdersChannelSubscribePayload, + relayerApiOrdersChannelUpdateSchema, + relayerApiOrdersResponseSchema, + relayerApiAssetDataPairsSchema, +} = jsonSchemas; + +const usedSchemas = { + numberSchema, + addressSchema, + hexSchema, + orderHashSchema, + orderSchema, + signedOrderSchema, + signedOrdersSchema, + ordersSchema, + paginatedCollectionSchema, + relayerApiErrorResponseSchema, + relayerApiFeeRecipientsResponseSchema, + relayerApiOrderSchema, + relayerApiOrdersSchema, + relayerApiOrderConfigPayloadSchema, + relayerApiOrderConfigResponseSchema, + relayerApiOrderBookResponseSchema, + relayerApiAssetDataPairsResponseSchema, + relayerApiAssetDataTradeInfoSchema, + relayerApiOrdersChannelSubscribeSchema, + relayerApiOrdersChannelSubscribePayload, + relayerApiOrdersChannelUpdateSchema, + relayerApiOrdersResponseSchema, + relayerApiAssetDataPairsSchema, +}; + +// We need to replace the `$ref`s to be OpenAPI compliant. +const openApiSchemas = JSON.parse( + JSON.stringify(usedSchemas).replace(/(\/\w+)/g, match => `#/components/schemas${match}`), +); +// The json schema used by OpenAPI does not accept ids +Object.keys(openApiSchemas).forEach(key => delete openApiSchemas[key].id); + +export const schemas = openApiSchemas; diff --git a/packages/sra-api/src/parameters.ts b/packages/sra-api/src/parameters.ts index bfa261df0..7b54fe9a0 100644 --- a/packages/sra-api/src/parameters.ts +++ b/packages/sra-api/src/parameters.ts @@ -25,7 +25,6 @@ export const networkdIdParameter: ParameterObject = { in: 'query', description: 'The id of the Ethereum network', example: 42, - default: 1, schema: { type: 'number', }, -- cgit v1.2.3 From 6121a6d2bffed7187a875148a5e36d0b4b7645ac Mon Sep 17 00:00:00 2001 From: fragosti Date: Wed, 8 Aug 2018 14:28:09 -0700 Subject: Add to changelog and fix OrderBook typo --- packages/sra-api/src/api.ts | 6 +++--- packages/sra-api/src/examples/index.ts | 4 ++-- packages/sra-api/src/examples/relayerApiOrderBookResponse.ts | 2 +- packages/sra-api/src/json-schemas.ts | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/api.ts b/packages/sra-api/src/api.ts index e578ddc74..c2236fda5 100644 --- a/packages/sra-api/src/api.ts +++ b/packages/sra-api/src/api.ts @@ -206,7 +206,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. `, - operationId: 'getOrderBook', + operationId: 'getOrderbook', parameters: generateParameters( [ { @@ -233,8 +233,8 @@ export const api: OpenApiSpec = { true, ), responses: generateResponses( - 'relayerApiOrderBookResponseSchema', - examples.relayerApiOrderBookResponse, + 'relayerApiOrderbookResponseSchema', + examples.relayerApiOrderbookResponse, `The sorted order book for the specified asset pair.`, ), }, diff --git a/packages/sra-api/src/examples/index.ts b/packages/sra-api/src/examples/index.ts index cdc4fac53..dcf9b13eb 100644 --- a/packages/sra-api/src/examples/index.ts +++ b/packages/sra-api/src/examples/index.ts @@ -2,7 +2,7 @@ import { validationError } from './errors'; import { relayerApiAssetDataPairsResponse } from './relayerApiAssetDataPairsResponse'; import { relayerApiFeeRecipientsResponse } from './relayerApiFeeRecipientsResponse'; import { relayerApiOrder } from './relayerApiOrder'; -import { relayerApiOrderBookResponse } from './relayerApiOrderBookResponse'; +import { relayerApiOrderbookResponse } from './relayerApiOrderbookResponse'; import { relayerApiOrderConfigPayload } from './relayerApiOrderConfigPayload'; import { relayerApiOrderConfigResponse } from './relayerApiOrderConfigResponse'; import { relayerApiOrdersResponse } from './relayerApiOrdersResponse'; @@ -13,7 +13,7 @@ export const examples = { relayerApiAssetDataPairsResponse, relayerApiFeeRecipientsResponse, relayerApiOrder, - relayerApiOrderBookResponse, + relayerApiOrderbookResponse, relayerApiOrderConfigPayload, relayerApiOrderConfigResponse, relayerApiOrdersResponse, diff --git a/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts b/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts index 4e1e7a8eb..40c09eff9 100644 --- a/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts +++ b/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts @@ -1,4 +1,4 @@ -export const relayerApiOrderBookResponse = { +export const relayerApiOrderbookResponse = { bids: { total: 325, page: 2, diff --git a/packages/sra-api/src/json-schemas.ts b/packages/sra-api/src/json-schemas.ts index 5b222a43f..173a04bfb 100644 --- a/packages/sra-api/src/json-schemas.ts +++ b/packages/sra-api/src/json-schemas.ts @@ -17,7 +17,7 @@ const { relayerApiOrdersSchema, relayerApiOrderConfigPayloadSchema, relayerApiOrderConfigResponseSchema, - relayerApiOrderBookResponseSchema, + relayerApiOrderbookResponseSchema, relayerApiAssetDataPairsResponseSchema, relayerApiAssetDataTradeInfoSchema, relayerApiOrdersChannelSubscribeSchema, @@ -43,7 +43,7 @@ const usedSchemas = { relayerApiOrdersSchema, relayerApiOrderConfigPayloadSchema, relayerApiOrderConfigResponseSchema, - relayerApiOrderBookResponseSchema, + relayerApiOrderbookResponseSchema, relayerApiAssetDataPairsResponseSchema, relayerApiAssetDataTradeInfoSchema, relayerApiOrdersChannelSubscribeSchema, -- cgit v1.2.3 From 083d42c8f778e8a88f21f179e3ec271f8a762268 Mon Sep 17 00:00:00 2001 From: fragosti Date: Wed, 8 Aug 2018 14:36:38 -0700 Subject: Fix links in markdown --- packages/sra-api/src/md/introduction.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index 4d0679f9e..f0dfb04b1 100644 --- a/packages/sra-api/src/md/introduction.md +++ b/packages/sra-api/src/md/introduction.md @@ -2,20 +2,20 @@ Requests that return potentially large collections should respond to the **?page** and **?per_page** 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&per_page=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](#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) **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. -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](#misc) about formatting `snake_case` vs. `lowerCamelCase`. +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`. -These requests include the [`asset_pairs`](#get-v2-asset-pairs), [`orders`](#get-v2-orders), and [`orderbook`](#get-v2-orderbook) endpoints. +These requests include the [`asset_pairs`](#operation/getAssetPairs), [`orders`](#operation/getOrders), and [`orderbook`](#operation/getOrderbook) endpoints. # Network Id All requests should be able to specify a **?networkId** query param for all supported networks. For example: -``` -curl https://api.example-relayer.com/v2/asset_pairs?networkId=1 +```bash +$ curl https://api.example-relayer.com/v2/asset_pairs?networkId=1 ``` If the query param is not provided, it should default to **1** (mainnet). @@ -28,7 +28,7 @@ Networks and their Ids: | 3 | Ropsten | | 4 | Rinkeby | - If a certain network is not supported, the response should **400** as specified in the [error response](#error-response) section. For example: + If a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example: ``` { -- cgit v1.2.3 From 9e3fe7092bd0fe1b9d00e8d619ad9b4ce90c3bf1 Mon Sep 17 00:00:00 2001 From: fragosti Date: Wed, 8 Aug 2018 14:47:43 -0700 Subject: Add section about json-schemas and sra report --- packages/sra-api/src/md/introduction.md | 34 +++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index f0dfb04b1..76a144225 100644 --- a/packages/sra-api/src/md/introduction.md +++ b/packages/sra-api/src/md/introduction.md @@ -1,3 +1,29 @@ +# Testing + +Use the [sra-report](https://github.com/0xProject/0x-monorepo/tree/development/packages/sra-report) command line tool to test your API for SRA compliance. + +# Schemas + +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; +const validator = new SchemaValidator(); + +const tokenPairsResponse = { + ... +}; +const validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, relayerApiTokenPairsResponseSchema); +``` + # Pagination Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example: @@ -6,11 +32,11 @@ Requests that return potentially large collections should respond to the **?page $ curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=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) `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. -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`. +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`. -These requests include the [`asset_pairs`](#operation/getAssetPairs), [`orders`](#operation/getOrders), and [`orderbook`](#operation/getOrderbook) endpoints. +These requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/orders`](#operation/getOrders), [`/v2/fee_recipients`](#operation/getFeeRecipients) and [`/v2/orderbook`](#operation/getOrderbook) endpoints. # Network Id All requests should be able to specify a **?networkId** query param for all supported networks. For example: @@ -78,7 +104,7 @@ Rate limit guidance for clients can be optionally returned in the response heade For example: ``` -curl -i https://api.example-relayer.com/v2/asset_pairs +$ curl -i https://api.example-relayer.com/v2/asset_pairs HTTP/1.1 200 OK Date: Mon, 20 Oct 2017 12:30:06 GMT Status: 200 OK -- cgit v1.2.3 From d7d51791a6bba5dae274c50257038b2bb8fb626b Mon Sep 17 00:00:00 2001 From: fragosti Date: Wed, 8 Aug 2018 14:50:06 -0700 Subject: Remove md hints because the static site cannot handle them --- packages/sra-api/src/md/introduction.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index 76a144225..27b0db729 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; @@ -28,7 +28,7 @@ const validatorResult: ValidatorResult = validator.validate(tokenPairsResponse, Requests that return potentially large collections should respond to the **?page** and **?per_page** parameters. For example: -```bash +``` $ curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=20 ``` @@ -40,7 +40,7 @@ These requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/ # Network Id 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 ``` If the query param is not provided, it should default to **1** (mainnet). -- cgit v1.2.3 From eb20e869472bbd7f463c331a236cae51e11cb27d Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 9 Aug 2018 09:39:29 -0700 Subject: Force case change in file --- .../src/examples/relayerApiOrderBookResponse.ts | 54 ---------------------- .../src/examples/relayerApiOrderbookResponse.ts | 54 ++++++++++++++++++++++ 2 files changed, 54 insertions(+), 54 deletions(-) delete mode 100644 packages/sra-api/src/examples/relayerApiOrderBookResponse.ts create mode 100644 packages/sra-api/src/examples/relayerApiOrderbookResponse.ts (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts b/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts deleted file mode 100644 index 40c09eff9..000000000 --- a/packages/sra-api/src/examples/relayerApiOrderBookResponse.ts +++ /dev/null @@ -1,54 +0,0 @@ -export const relayerApiOrderbookResponse = { - 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: {}, - }, - ], - }, -}; diff --git a/packages/sra-api/src/examples/relayerApiOrderbookResponse.ts b/packages/sra-api/src/examples/relayerApiOrderbookResponse.ts new file mode 100644 index 000000000..40c09eff9 --- /dev/null +++ b/packages/sra-api/src/examples/relayerApiOrderbookResponse.ts @@ -0,0 +1,54 @@ +export const relayerApiOrderbookResponse = { + 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: {}, + }, + ], + }, +}; -- cgit v1.2.3 From b2c666bb1f2830211db208ba8398f2de799c8ee6 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 9 Aug 2018 11:42:05 -0700 Subject: Apply prettier --- packages/sra-api/src/md/introduction.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/md/introduction.md b/packages/sra-api/src/md/introduction.md index 27b0db729..3e5e84e4c 100644 --- a/packages/sra-api/src/md/introduction.md +++ b/packages/sra-api/src/md/introduction.md @@ -34,15 +34,18 @@ $ curl https://api.example-relayer.com/v2/asset_pairs?page=3&per_page=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. -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`. +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`. These requests include the [`/v2/asset_pairs`](#operation/getAssetPairs), [`/v2/orders`](#operation/getOrders), [`/v2/fee_recipients`](#operation/getFeeRecipients) and [`/v2/orderbook`](#operation/getOrderbook) endpoints. # Network Id + All requests should be able to specify a **?networkId** query param for all supported networks. For example: + ``` $ curl https://api.example-relayer.com/v2/asset_pairs?networkId=1 ``` + If the query param is not provided, it should default to **1** (mainnet). Networks and their Ids: @@ -54,8 +57,8 @@ Networks and their Ids: | 3 | Ropsten | | 4 | Rinkeby | - If a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example: - +If a certain network is not supported, the response should **400** as specified in the [error response](#section/Errors) section. For example: + ``` { "code": 100, @@ -112,6 +115,7 @@ X-RateLimit-Limit: 60 X-RateLimit-Remaining: 56 X-RateLimit-Reset: 1372700873 ``` + When a rate limit is exceeded, a status of **429 Too Many Requests** should be returned. # Errors @@ -129,6 +133,7 @@ Unless the spec defines otherwise, errors to bad requests should respond with HT | 501 | Not Implemented | ## Error reporting format + 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). ``` @@ -168,9 +173,10 @@ Validation error codes: # Asset Data Encoding -As 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). +As 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). The identifier for the Proxy uses a similar scheme to [ABI function selectors](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#function-selector). + ``` // ERC20 Proxy ID 0xf47261b0 bytes4(keccak256("ERC20Token(address)")) @@ -178,14 +184,16 @@ bytes4(keccak256("ERC20Token(address)")) bytes4(keccak256("ERC721Token(address,uint256)")) ``` -Asset data is encoded using [ABI encoding](https://solidity.readthedocs.io/en/develop/abi-spec.html). +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: -For example, encoding the ERC20 token contract (address: 0x1dc4c1cefef38a777b15aa20260a54e584b16c48) using the ERC20 Transfer Proxy (id: 0xf47261b0) would be: ``` 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: + ``` 0x08e937fa000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063 ``` -- cgit v1.2.3 From 2f66f26048af6e1edb415fd632dbb2e078cb8597 Mon Sep 17 00:00:00 2001 From: fragosti Date: Thu, 9 Aug 2018 16:41:43 -0700 Subject: Fix linting issues --- packages/sra-api/src/parameters.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'packages/sra-api/src') diff --git a/packages/sra-api/src/parameters.ts b/packages/sra-api/src/parameters.ts index 7b54fe9a0..7d63a0a18 100644 --- a/packages/sra-api/src/parameters.ts +++ b/packages/sra-api/src/parameters.ts @@ -1,4 +1,4 @@ -import { ParameterLocation, ParameterObject } from '@loopback/openapi-v3-types'; +import { ParameterObject } from '@loopback/openapi-v3-types'; export const paginationParameters: ParameterObject[] = [ { name: 'page', -- cgit v1.2.3