{"_id":"56c5062cbdcde80d0049866f","createdAt":"2015-02-19T22:17:46.149Z","githubsync":"","link_external":false,"api":{"auth":"required","params":[],"results":{"codes":[]},"settings":"","url":""},"category":"56c50628bdcde80d00498636","updates":[],"parentDoc":null,"project":"54774d9af3736008009e9e0e","hidden":false,"isReference":false,"sync_unique":"","title":"API Reference Overview","user":"54ad5f42921992210075173e","__v":3,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication & authorization\"\n}\n[/block]\nThere are a few options to authorize your calls:\n\n- add the `AUTHORIZATION` header\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n-H \\\"AUTHORIZATION: token <API_KEY>\\\" \\\\ \\\"https://api.syncano.io/v1.1/instances/<instance>/\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n- add the `X-API-KEY` header\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\\\\n-H \\\"X-API-KEY: <API_KEY>\\\" \\\\\\n\\\"https://api.syncano.io/v1.1/instances/<instance>/\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n- add the `api_key` query parameter to request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl \\\"https://api.syncano.io/v1.1/instances/?api_key=<API_KEY>\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Paging\"\n}\n[/block]\nExample for Script traces:\nWe use direction `1`, or `0` and `last_pk`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"next\\\": \\\"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/?direction=1&last_pk=11268\\\",\\n    \\\"prev\\\": \\\"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/?direction=0&last_pk=11367\\\",\\n    \\\"objects\\\": [\\n        {\\n            \\\"id\\\": 11367,\\n            \\\"status\\\": \\\"success\\\",\\n            \\\"executed_at\\\": \\\"2015-01-21T12:18:08.791108Z\\\",\\n            \\\"duration\\\": 365,\\n            \\\"result\\\": \\\"uh ah!\\\",\\n            \\\"links\\\": {\\n                \\\"self\\\": \\\"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/11367/\\\"\\n            }\\n        },\\n        ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n### Changing page size\n\nThe number of items by page is set with the `page_size` query parameter.\n\n### Different orderings\n\nOn the data object endpoint, we can order by different values with the `order_by` parameter.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Ideas behind the API design\"\n}\n[/block]\n### API urls\n\nThe Syncano API is a nested API, most of the endpoints are prefixed by `instances/<instance_name>/something/`\n\nThis is because of the tenancy architecture of the Syncano backend. Every instance is completely separated from another, so the data class with a name `testclass` on one instance can be totally different from another data class `testclass` on a different instance.\n\n### HATEOAS - links\n\nWe use HATEOAS in our REST API. If you don't know what a HATEOAS is, [grab a link](http://stackoverflow.com/questions/9192648/hateoas-concise-description).\n\nIn the Syncano API, every resource has links to other resources. Below is an example for the instance:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"mytestinstance\\\",\\n    \\\"description\\\": \\\"this and that\\\",\\n    \\\"owner\\\": {\\n        \\\"id\\\": 10,\\n        \\\"email\\\": \\\"justyna.ilczuk:::at:::gmail.com\\\",\\n        \\\"first_name\\\": \\\"Justyna\\\",\\n        \\\"last_name\\\": \\\"Ilczuk\\\"\\n    },\\n    \\\"created_at\\\": \\\"2015-01-21T15:25:31.887657Z\\\",\\n    \\\"updated_at\\\": \\\"2015-01-21T15:25:31.909999Z\\\",\\n    \\\"role\\\": \\\"full\\\",\\n    \\\"links\\\": {\\n        \\\"triggers\\\": \\\"/v1.1/instances/mytestinstance/triggers/\\\",\\n        \\\"self\\\": \\\"/v1.1/instances/mytestinstance/\\\",\\n        \\\"invitations\\\": \\\"/v1.1/instances/mytestinstance/invitations/\\\",\\n        \\\"admins\\\": \\\"/v1.1/instances/mytestinstance/admins/\\\",\\n        \\\"classes\\\": \\\"/v1.1/instances/mytestinstance/classes/\\\",\\n        \\\"script_runtimes\\\": \\\"/v1.1/instances/mytestinstance/snippets/scripts/runtimes/\\\",\\n        \\\"endpoints\\\": \\\"/v1.1/instances/mytestinstance/endpoints/\\\",\\n        \\\"api_keys\\\": \\\"/v1.1/instances/mytestinstance/api_keys/\\\",\\n        \\\"scripts\\\": \\\"/v1.1/instances/mytestinstance/snippets/scripts/\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n### Options method on endpoints\n\nYou might find it useful to make OPTIONS requests on endpoints to get more details about them.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X OPTIONS \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-H \\\"X-API-KEY: <API_KEY>\\\" \\\\\\n\\\"https://api.syncano.io/v1.1/instances/<my_instance>/classes/\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{  \\n   \\\"parses\\\":[  \\n      \\\"application\\\\/json\\\",\\n      \\\"application\\\\/x-www-form-urlencoded\\\",\\n      \\\"multipart\\\\/form-data\\\"\\n   ],\\n   \\\"renders\\\":[  \\n      \\\"application\\\\/json\\\",\\n      \\\"text\\\\/html\\\"\\n   ],\\n   \\\"name\\\":\\\"Class List\\\",\\n   \\\"actions\\\":{  \\n      \\\"POST\\\":{  \\n         \\\"status\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"field\\\"\\n         },\\n         \\\"group\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"field\\\",\\n            \\\"label\\\":\\\"group\\\"\\n         },\\n         \\\"name\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"max_length\\\":50,\\n            \\\"required\\\":true,\\n            \\\"type\\\":\\\"string\\\",\\n            \\\"label\\\":\\\"name\\\"\\n         },\\n         \\\"links\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"links\\\",\\n            \\\"links\\\":[  \\n               {  \\n                  \\\"type\\\":\\\"detail\\\",\\n                  \\\"name\\\":\\\"self\\\"\\n               },\\n               {  \\n                  \\\"type\\\":\\\"list\\\",\\n                  \\\"name\\\":\\\"objects\\\"\\n               },\\n               {  \\n                  \\\"type\\\":\\\"detail\\\",\\n                  \\\"name\\\":\\\"group\\\"\\n               }\\n            ]\\n         },\\n         \\\"group_permissions\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":true,\\n            \\\"type\\\":\\\"choice\\\",\\n            \\\"choices\\\":[  \\n               {  \\n                  \\\"display_name\\\":\\\"none\\\",\\n                  \\\"value\\\":\\\"none\\\"\\n               },\\n               {  \\n                  \\\"display_name\\\":\\\"read\\\",\\n                  \\\"value\\\":\\\"read\\\"\\n               },\\n               {  \\n                  \\\"display_name\\\":\\\"create_objects\\\",\\n                  \\\"value\\\":\\\"create_objects\\\"\\n               }\\n            ]\\n         },\\n         \\\"created_at\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"datetime\\\",\\n            \\\"label\\\":\\\"created at\\\"\\n         },\\n         \\\"description\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"string\\\",\\n            \\\"label\\\":\\\"description\\\"\\n         },\\n         \\\"updated_at\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"datetime\\\",\\n            \\\"label\\\":\\\"updated at\\\"\\n         },\\n         \\\"objects_count\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"field\\\"\\n         },\\n         \\\"metadata\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":false,\\n            \\\"type\\\":\\\"field\\\",\\n            \\\"label\\\":\\\"metadata\\\"\\n         },\\n         \\\"revision\\\":{  \\n            \\\"read_only\\\":true,\\n            \\\"required\\\":true,\\n            \\\"type\\\":\\\"integer\\\",\\n            \\\"label\\\":\\\"revision\\\"\\n         },\\n         \\\"other_permissions\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":true,\\n            \\\"type\\\":\\\"choice\\\",\\n            \\\"choices\\\":[  \\n               {  \\n                  \\\"display_name\\\":\\\"none\\\",\\n                  \\\"value\\\":\\\"none\\\"\\n               },\\n               {  \\n                  \\\"display_name\\\":\\\"read\\\",\\n                  \\\"value\\\":\\\"read\\\"\\n               },\\n               {  \\n                  \\\"display_name\\\":\\\"create_objects\\\",\\n                  \\\"value\\\":\\\"create_objects\\\"\\n               }\\n            ]\\n         },\\n         \\\"schema\\\":{  \\n            \\\"read_only\\\":false,\\n            \\\"required\\\":true,\\n            \\\"type\\\":\\\"field\\\",\\n            \\\"label\\\":\\\"schema\\\"\\n         }\\n      }\\n   },\\n   \\\"description\\\":\\\"\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n### Schema endpoint\n\nThe API has a schema endpoint that describes every endpoint, methods, and parameters in a consistent way.\n\nhttps://api.syncano.io/v1.1/schema/","link_url":"","order":0,"slug":"general-information","type":"basic","version":"56c50626bdcde80d00498635","excerpt":"","childrenPages":[]}

API Reference Overview


[block:api-header] { "type": "basic", "title": "Authentication & authorization" } [/block] There are a few options to authorize your calls: - add the `AUTHORIZATION` header [block:code] { "codes": [ { "code": "curl \\\n-H \"AUTHORIZATION: token <API_KEY>\" \\ \"https://api.syncano.io/v1.1/instances/<instance>/\"", "language": "curl" } ] } [/block] - add the `X-API-KEY` header [block:code] { "codes": [ { "code": "curl \\\n-H \"X-API-KEY: <API_KEY>\" \\\n\"https://api.syncano.io/v1.1/instances/<instance>/\"", "language": "curl" } ] } [/block] - add the `api_key` query parameter to request [block:code] { "codes": [ { "code": "curl \"https://api.syncano.io/v1.1/instances/?api_key=<API_KEY>\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Paging" } [/block] Example for Script traces: We use direction `1`, or `0` and `last_pk`: [block:code] { "codes": [ { "code": "{\n \"next\": \"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/?direction=1&last_pk=11268\",\n \"prev\": \"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/?direction=0&last_pk=11367\",\n \"objects\": [\n {\n \"id\": 11367,\n \"status\": \"success\",\n \"executed_at\": \"2015-01-21T12:18:08.791108Z\",\n \"duration\": 365,\n \"result\": \"uh ah!\",\n \"links\": {\n \"self\": \"/v1.1/instances/syncano/snippets/scripts/1/schedules/4/traces/11367/\"\n }\n },\n ...\n}", "language": "json" } ] } [/block] ### Changing page size The number of items by page is set with the `page_size` query parameter. ### Different orderings On the data object endpoint, we can order by different values with the `order_by` parameter. [block:api-header] { "type": "basic", "title": "Ideas behind the API design" } [/block] ### API urls The Syncano API is a nested API, most of the endpoints are prefixed by `instances/<instance_name>/something/` This is because of the tenancy architecture of the Syncano backend. Every instance is completely separated from another, so the data class with a name `testclass` on one instance can be totally different from another data class `testclass` on a different instance. ### HATEOAS - links We use HATEOAS in our REST API. If you don't know what a HATEOAS is, [grab a link](http://stackoverflow.com/questions/9192648/hateoas-concise-description). In the Syncano API, every resource has links to other resources. Below is an example for the instance: [block:code] { "codes": [ { "code": "{\n \"name\": \"mytestinstance\",\n \"description\": \"this and that\",\n \"owner\": {\n \"id\": 10,\n \"email\": \"[email protected]\",\n \"first_name\": \"Justyna\",\n \"last_name\": \"Ilczuk\"\n },\n \"created_at\": \"2015-01-21T15:25:31.887657Z\",\n \"updated_at\": \"2015-01-21T15:25:31.909999Z\",\n \"role\": \"full\",\n \"links\": {\n \"triggers\": \"/v1.1/instances/mytestinstance/triggers/\",\n \"self\": \"/v1.1/instances/mytestinstance/\",\n \"invitations\": \"/v1.1/instances/mytestinstance/invitations/\",\n \"admins\": \"/v1.1/instances/mytestinstance/admins/\",\n \"classes\": \"/v1.1/instances/mytestinstance/classes/\",\n \"script_runtimes\": \"/v1.1/instances/mytestinstance/snippets/scripts/runtimes/\",\n \"endpoints\": \"/v1.1/instances/mytestinstance/endpoints/\",\n \"api_keys\": \"/v1.1/instances/mytestinstance/api_keys/\",\n \"scripts\": \"/v1.1/instances/mytestinstance/snippets/scripts/\"\n }\n}", "language": "json" } ] } [/block] ### Options method on endpoints You might find it useful to make OPTIONS requests on endpoints to get more details about them. [block:code] { "codes": [ { "code": "curl -X OPTIONS \\\n-H \"Content-type: application/json\" \\\n-H \"X-API-KEY: <API_KEY>\" \\\n\"https://api.syncano.io/v1.1/instances/<my_instance>/classes/\"", "language": "curl" } ] } [/block] [block:code] { "codes": [ { "code": "{ \n \"parses\":[ \n \"application\\/json\",\n \"application\\/x-www-form-urlencoded\",\n \"multipart\\/form-data\"\n ],\n \"renders\":[ \n \"application\\/json\",\n \"text\\/html\"\n ],\n \"name\":\"Class List\",\n \"actions\":{ \n \"POST\":{ \n \"status\":{ \n \"read_only\":true,\n \"required\":false,\n \"type\":\"field\"\n },\n \"group\":{ \n \"read_only\":false,\n \"required\":false,\n \"type\":\"field\",\n \"label\":\"group\"\n },\n \"name\":{ \n \"read_only\":false,\n \"max_length\":50,\n \"required\":true,\n \"type\":\"string\",\n \"label\":\"name\"\n },\n \"links\":{ \n \"read_only\":true,\n \"required\":false,\n \"type\":\"links\",\n \"links\":[ \n { \n \"type\":\"detail\",\n \"name\":\"self\"\n },\n { \n \"type\":\"list\",\n \"name\":\"objects\"\n },\n { \n \"type\":\"detail\",\n \"name\":\"group\"\n }\n ]\n },\n \"group_permissions\":{ \n \"read_only\":false,\n \"required\":true,\n \"type\":\"choice\",\n \"choices\":[ \n { \n \"display_name\":\"none\",\n \"value\":\"none\"\n },\n { \n \"display_name\":\"read\",\n \"value\":\"read\"\n },\n { \n \"display_name\":\"create_objects\",\n \"value\":\"create_objects\"\n }\n ]\n },\n \"created_at\":{ \n \"read_only\":true,\n \"required\":false,\n \"type\":\"datetime\",\n \"label\":\"created at\"\n },\n \"description\":{ \n \"read_only\":false,\n \"required\":false,\n \"type\":\"string\",\n \"label\":\"description\"\n },\n \"updated_at\":{ \n \"read_only\":true,\n \"required\":false,\n \"type\":\"datetime\",\n \"label\":\"updated at\"\n },\n \"objects_count\":{ \n \"read_only\":true,\n \"required\":false,\n \"type\":\"field\"\n },\n \"metadata\":{ \n \"read_only\":false,\n \"required\":false,\n \"type\":\"field\",\n \"label\":\"metadata\"\n },\n \"revision\":{ \n \"read_only\":true,\n \"required\":true,\n \"type\":\"integer\",\n \"label\":\"revision\"\n },\n \"other_permissions\":{ \n \"read_only\":false,\n \"required\":true,\n \"type\":\"choice\",\n \"choices\":[ \n { \n \"display_name\":\"none\",\n \"value\":\"none\"\n },\n { \n \"display_name\":\"read\",\n \"value\":\"read\"\n },\n { \n \"display_name\":\"create_objects\",\n \"value\":\"create_objects\"\n }\n ]\n },\n \"schema\":{ \n \"read_only\":false,\n \"required\":true,\n \"type\":\"field\",\n \"label\":\"schema\"\n }\n }\n },\n \"description\":\"\"\n}", "language": "json" } ] } [/block] ### Schema endpoint The API has a schema endpoint that describes every endpoint, methods, and parameters in a consistent way. https://api.syncano.io/v1.1/schema/