{"_id":"582789abbe5c080f00a5a820","__v":0,"category":{"_id":"587aeb9a01cf3a0f008359eb","project":"568bdc1483d2061900d86cdc","version":"582789aabe5c080f00a5a7fe","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-01-15T03:25:14.326Z","from_sync":false,"order":3,"slug":"using-the-api","title":"Using the API"},"project":"568bdc1483d2061900d86cdc","parentDoc":null,"user":"568bdbc4fe6fcc0d006dc970","version":{"_id":"582789aabe5c080f00a5a7fe","__v":10,"project":"568bdc1483d2061900d86cdc","createdAt":"2016-11-12T21:29:14.915Z","releaseDate":"2016-11-12T21:29:14.915Z","categories":["582789abbe5c080f00a5a7ff","582789abbe5c080f00a5a800","582789abbe5c080f00a5a801","582789abbe5c080f00a5a802","582789abbe5c080f00a5a803","582789abbe5c080f00a5a804","582789abbe5c080f00a5a805","582789abbe5c080f00a5a806","582789abbe5c080f00a5a807","582789abbe5c080f00a5a808","5827ea984ca29e0f00137a9e","583df597887db62f00644283","583df5d9c622791900e78da5","5845cd8763c11b250037967d","5845d13063c11b2500379681","5859e859e3306d1900126725","587aeb9a01cf3a0f008359eb","587c422af45e2d0f005e200d","587d84dc82f6f30f004ceee5"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta2","version_clean":"0.0.0","version":"0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-09T14:16:53.280Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"You can discover the invocation format for any API endpoint in droplit.io with an OPTIONS call.\n\nAn OPTIONS call is traditionally used to indicate to the browser what HTTP verbs are allowed. We’ve added a body to the response that details the call format of each endpoint.\n\n# Schema Structure\n\nThe OPTIONS response contains Swagger-inspired JSON describing the allowed methods and parameters at the requested end-point. At the top-level, are key-value pairs with the _method_ name (e.g., GET, POST, etc.) as the key and an object as the value. The value object contains a text _description_ and an object for _parameters_. The parameters object itself is a key-value pair with the parameter name as the key and an object representing the parameter information as the value.\n\n## Parameter Data\n\n### in\nA `string` representing where the parameter is located.\nAvailable values:\n* body - Parameter is in the request’s message body.\n* path - Parameter is in the request’s URI path. E.g., in `/devices/:id`, id is the path parameter.\n* query - Parameter is in the request’s URI query string. E.g., in `/devices?environmentId=*` environmentId is the query parameter.\n\n### type\nA `string` representing the data type of the parameter. Available values are: `string`, `number`, `integer`, `object`, `array`, and `boolean`.\n\n### required\nA `boolean` representing whether the parameter is required for the request.\n\n### items\nAn `object` describing the type of items in the array. Only applies when the type is array.\n\nE.g., in the following parameter schema, the value of `services` is an array of strings:\n``` JSON\n\"services\": {\n    \"in\": \"body\",\n    \"type\": \"array\",\n    \"required\": false,\n    \"items\": { \"type\": \"string\" }\n}\n```\n\n### match\nA `RegExp` pattern that the parameter value must adhere to. Only applies when the type is string.\n\n### minimum\nAn `integer` value representing the minimum value (inclusive) that the parameter value may be. Only applies when the type is a number or integer.\n\n### maximum\nAn `integer` value representing the maximum value (inclusive) that the parameter value may be. Only applies when the type is a number or integer\n\n### minLength\nAn `integer` value representing the minimum length (inclusive) that the parameter value may be. Only applies when the type is string.\n\n### maxLength\nAn `integer` value representing the maximum length (inclusive) that the parameter value may be. Only applies when the type is string.\n\n### enum\nAn `array` value representing a fixed set of values available for the parameter value.\n\nE.g., in the following parameter schema, the value of `expiryType` will be constrained to the strings: `Infinite`, `FixedTtl`, and `SlidingTtl`.\n``` JSON\n\"expiryType\": {\n    \"in\": \"query\",\n    \"type\": \"string\",\n    \"enum\": [ \"Infinite\", \"FixedTtl\", \"SlidingTtl\" ],\n    \"required\": false\n}\n```\n\n# Examples\n\nIn the example below, some header fields have been removed for clarity.\n\n`OPTIONS https://ioe.droplit.io/api/ecosystems`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 200 OK\\naccess-control-allow-origin: *\\naccess-control-allow-methods: GET,POST,OPTIONS\\n\\n{\\n    \\\"get\\\": {\\n        \\\"description\\\": \\\"List all ecosystems\\\"\\n    },\\n    \\\"post\\\": {\\n        \\\"description\\\": \\\"Create an ecosystem\\\",\\n        \\\"parameters\\\": {\\n            \\\"meta\\\": {\\n            \\t\\t\\\"in\\\": \\\"body\\\",\\n                \\\"type\\\": \\\"object\\\",\\n                \\\"required\\\": false\\n            }\\n        }\\n    }\\n}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n`OPTIONS https://ioe.droplit.io/api/ecosystems/C57146c78149e6c3039e708b6`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 200 OK\\naccess-control-allow-origin: *\\naccess-control-allow-methods: DELETE,GET,PUT,OPTIONS\\n\\n{\\n    \\\"delete\\\": {\\n        \\\"description\\\": \\\"Delete a specified ecosystem\\\",\\n        \\\"parameters\\\": {\\n            \\\"id\\\": {\\n            \\t\\t\\\"in\\\": \\\"path\\\",\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"match\\\": \\\"^[A-Z]{1}[a-z0-9]{24}$\\\",\\n                \\\"required\\\": true\\n            }\\n        }\\n    },\\n    \\\"get\\\": {\\n        \\\"description\\\": \\\"Get a specified ecosystem\\\",\\n        \\\"parameters\\\": {\\n            \\\"id\\\": {\\n            \\t\\t\\\"in\\\": \\\"path\\\",\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"match\\\": \\\"^[A-Z]{1}[a-z0-9]{24}$\\\",\\n                \\\"required\\\": true\\n            }\\n        }\\n    },\\n    \\\"put\\\": {\\n        \\\"description\\\": \\\"Update a specified ecosystem\\\",\\n        \\\"parameters\\\": {\\n            \\\"meta\\\": {\\n            \\t\\t\\\"in\\\": \\\"body\\\",\\n                \\\"type\\\": \\\"object\\\",\\n                \\\"required\\\": false\\n            },\\n            \\\"id\\\": {\\n            \\t\\t\\\"in\\\": \\\"path\\\",\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"match\\\": \\\"^[A-Z]{1}[a-z0-9]{24}$\\\",\\n                \\\"required\\\": true\\n            }\\n        }\\n    }\\n}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]","excerpt":"Discovering the API programmatically with HTTP OPTIONS","slug":"options","type":"basic","title":"API discovery"}

API discovery

Discovering the API programmatically with HTTP OPTIONS

You can discover the invocation format for any API endpoint in droplit.io with an OPTIONS call. An OPTIONS call is traditionally used to indicate to the browser what HTTP verbs are allowed. We’ve added a body to the response that details the call format of each endpoint. # Schema Structure The OPTIONS response contains Swagger-inspired JSON describing the allowed methods and parameters at the requested end-point. At the top-level, are key-value pairs with the _method_ name (e.g., GET, POST, etc.) as the key and an object as the value. The value object contains a text _description_ and an object for _parameters_. The parameters object itself is a key-value pair with the parameter name as the key and an object representing the parameter information as the value. ## Parameter Data ### in A `string` representing where the parameter is located. Available values: * body - Parameter is in the request’s message body. * path - Parameter is in the request’s URI path. E.g., in `/devices/:id`, id is the path parameter. * query - Parameter is in the request’s URI query string. E.g., in `/devices?environmentId=*` environmentId is the query parameter. ### type A `string` representing the data type of the parameter. Available values are: `string`, `number`, `integer`, `object`, `array`, and `boolean`. ### required A `boolean` representing whether the parameter is required for the request. ### items An `object` describing the type of items in the array. Only applies when the type is array. E.g., in the following parameter schema, the value of `services` is an array of strings: ``` JSON "services": { "in": "body", "type": "array", "required": false, "items": { "type": "string" } } ``` ### match A `RegExp` pattern that the parameter value must adhere to. Only applies when the type is string. ### minimum An `integer` value representing the minimum value (inclusive) that the parameter value may be. Only applies when the type is a number or integer. ### maximum An `integer` value representing the maximum value (inclusive) that the parameter value may be. Only applies when the type is a number or integer ### minLength An `integer` value representing the minimum length (inclusive) that the parameter value may be. Only applies when the type is string. ### maxLength An `integer` value representing the maximum length (inclusive) that the parameter value may be. Only applies when the type is string. ### enum An `array` value representing a fixed set of values available for the parameter value. E.g., in the following parameter schema, the value of `expiryType` will be constrained to the strings: `Infinite`, `FixedTtl`, and `SlidingTtl`. ``` JSON "expiryType": { "in": "query", "type": "string", "enum": [ "Infinite", "FixedTtl", "SlidingTtl" ], "required": false } ``` # Examples In the example below, some header fields have been removed for clarity. `OPTIONS https://ioe.droplit.io/api/ecosystems` [block:code] { "codes": [ { "code": "HTTP/1.1 200 OK\naccess-control-allow-origin: *\naccess-control-allow-methods: GET,POST,OPTIONS\n\n{\n \"get\": {\n \"description\": \"List all ecosystems\"\n },\n \"post\": {\n \"description\": \"Create an ecosystem\",\n \"parameters\": {\n \"meta\": {\n \t\t\"in\": \"body\",\n \"type\": \"object\",\n \"required\": false\n }\n }\n }\n}", "language": "http" } ] } [/block] `OPTIONS https://ioe.droplit.io/api/ecosystems/C57146c78149e6c3039e708b6` [block:code] { "codes": [ { "code": "HTTP/1.1 200 OK\naccess-control-allow-origin: *\naccess-control-allow-methods: DELETE,GET,PUT,OPTIONS\n\n{\n \"delete\": {\n \"description\": \"Delete a specified ecosystem\",\n \"parameters\": {\n \"id\": {\n \t\t\"in\": \"path\",\n \"type\": \"string\",\n \"match\": \"^[A-Z]{1}[a-z0-9]{24}$\",\n \"required\": true\n }\n }\n },\n \"get\": {\n \"description\": \"Get a specified ecosystem\",\n \"parameters\": {\n \"id\": {\n \t\t\"in\": \"path\",\n \"type\": \"string\",\n \"match\": \"^[A-Z]{1}[a-z0-9]{24}$\",\n \"required\": true\n }\n }\n },\n \"put\": {\n \"description\": \"Update a specified ecosystem\",\n \"parameters\": {\n \"meta\": {\n \t\t\"in\": \"body\",\n \"type\": \"object\",\n \"required\": false\n },\n \"id\": {\n \t\t\"in\": \"path\",\n \"type\": \"string\",\n \"match\": \"^[A-Z]{1}[a-z0-9]{24}$\",\n \"required\": true\n }\n }\n }\n}", "language": "http" } ] } [/block]