Create asset_pairs SRA endpoint (and establish conventions)

3 files changed, 81 insertions, 171 deletions

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',
+            },
+        },
+    ],
+};