swagger/_datasources.json
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://portal.28.io/v1",
"resourcePath": "/_datasources",
"produces": [
"application/json"
],
"description": "<p>These resources can be used to manage and explore data sources. The endpoint of these resources is based on your project name. For instance, if your 28.io project is named <code>myproject</code>, your endpoint for this API will be will be: <code>http://myproject.28.io/v1/_datasources</code>.</p>",
"apis": [
{
"path": "/_datasources",
"description": "Data Source Listing",
"operations": [
{
"method": "GET",
"summary": "Lists all data sources",
"notes": "<p>This method retrieves the data sources that are configured for a project.</p>",
"type": "array",
"items": {
"$ref": "Datasource"
},
"nickname": "listDatasources",
"parameters": [
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns the list of data sources."
}
],
"examples": [
{
"description": "The following request retrieves the list of data sources configured for the project.",
"title": "Listing data sources",
"request": "curl -X GET \"http://myproject.28.io/v1/_datasources?token=Rldtayt1YzV5a05FYlRvUFdqc0d4aGcveHJjPToyMDEzLTExLTA2VDA1OjM1OjUzLjk4Njg3N1o=\"",
"response": "< 200 OK\n[ {\n \"category\" : \"MongoDB\",\n \"name\" : \"xbrl\",\n \"default\" : false\n}, {\n \"category\" : \"MongoDB\",\n \"name\" : \"stackoverflow\",\n \"default\" : false\n} ]"
}
]
}
]
},
{
"path": "/_datasources/{category}",
"description": "Data Sources Management",
"operations": [
{
"method": "GET",
"summary": "Lists all data sources in a specific category",
"notes": "<p>This method retrieves the list of data sources from a specific category configured for the project. If no data source is present in the specified category an empty array is returned.</p>",
"type": "array",
"items": {
"$ref": "Datasource"
},
"nickname": "listCategoryDatasources",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns list of all data sources in the specified category."
}
],
"examples": [
{
"title": "Listing MongoDB data sources",
"description": "The following request retrieves the list of MongoDB data sources configured for this project.",
"request": "curl -X GET \"http://myproject.28.io/v1/_datasources/MongoDB?token=Rldtayt1YzV5a05FYlRvUFdqc0d4aGcveHJjPToyMDEzLTExLTA2VDA1OjM1OjUzLjk4Njg3N1o=\"",
"response": "< 200 OK\n[ {\n \"category\" : \"MongoDB\",\n \"name\" : \"xbrl\",\n \"default\" : false\n}, {\n \"category\" : \"MongoDB\",\n \"name\" : \"stackoverflow\",\n \"default\" : false\n} ]"
}
]
},
{
"method": "POST",
"summary": "Creates a new data source",
"notes": "<p>This method creates a new data source. According to the specified data source category, the connection to the data source will be tested within this method. If the test does not pass the credentials will not be stored and the reponse status code will be set to 422.</p><p class=\"callout-warning\">Currently, the default MongoDB data source cannot be created using this method.</p>",
"type": "Success",
"nickname": "createDatasource",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "name",
"description": "The name of the data source. The data source name can contain any alphabetic letter, numbers, dots, or dashes, and must start with an alphabetic letter.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "default",
"description": "Whether the new data source will be the default one for its category. The default value is false.",
"required": false,
"type": "boolean",
"paramType": "query"
},
{
"name": "credentials",
"description": "The data sources credentials as JSON.",
"required": true,
"type": "string",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 409,
"message": "The specified data source already exist.",
"responseModel": "Error"
},
{
"code": 422,
"message": "The test of the specified credentials has failed.",
"responseModel": "Tests"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 201,
"message": "The data source has been created."
}
],
"examples": [
{
"title": "Creating a new MongoDB data source",
"description": "The following request creates a new MongoDB data source.",
"request": "curl -H \"Content-Type: application/json; charset=utf-8\" -d \"{ \"conn-string\": \"linus.mongohq.com:10059\", \"db\": \"stackoverflow\", \"pass\": \"demo\", \"user\": \"demo\" }\" -X POST http://myproject.28.io/v1/_datasources/MongoDB?name=stackoverflow&default=false&token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 201 Created\n{\n \"success\" : true\n}"
}
]
}
]
},
{
"path": "/_datasources/{category}/{datasource}",
"operations": [
{
"method": "GET",
"summary": "Retrieves a data source credentials",
"notes": "<p>This method retrieves credentials from data source.</p><p class=\"callout-warning\">Currently, the default MongoDB credentials cannot be retrieved using this method.</p>",
"type": "object",
"nickname": "getDatasource",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source does not exist.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns data source credentials."
}
],
"examples": [
{
"title": "Retrieving credentials of a data source",
"description": "The following request retrieves the credentials of a MongoDB data source.",
"request": "curl -X GET \"http://myproject.28.io/v1/_datasources/MongoDB/stackoverflow?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=\"",
"response": "< 200 OK\n{\n \"conn-string\" : \"linus.mongohq.com:10059\",\n \"db\" : \"stackoverflow\",\n \"user\" : \"foo\",\n \"bar\" : \"demo\"\n}"
}
]
},
{
"method": "PATCH",
"summary": "Updates a data source",
"notes": "<p>This method updates a data source changing its name, whether it is default or not, or its credentials. At least one change, that is, one of the optional parameters, must be specified.</p><p class=\"callout-warning\">Currently, the default MongoDB data source cannot be modified through this method.</p>",
"type": "Success",
"nickname": "updateDatasource",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "name",
"description": "The new name of the data source. If not specified the data source is not renamed.",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "default",
"description": "Whether the data source should become (if true) or cease to be (if false) the default one for its category. If not specified the data source does not change its default status.",
"required": false,
"type": "boolean",
"paramType": "query"
},
{
"name": "credentials",
"description": "The new data sources credentials as JSON. If not specified the data sources credentials are not changed",
"required": false,
"type": "string",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source cannot be found.",
"responseModel": "Error"
},
{
"code": 422,
"message": "The connection test using the specified credentials has failed.",
"responseModel": "Tests"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The data source has been updated."
}
],
"examples": [
{
"title": "Updating a MongoDB data source",
"description": "The following request renames a MongoDB data source from <code>stackoverflow</code> to <code>newName</code>.",
"request": "curl -X PATCH http://myproject.28.io/v1/_datasources/MongoDB/stackoverflow?name=newName&token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"success\" : true\n}"
}
]
},
{
"method": "DELETE",
"summary": "Removes a data source",
"notes": "<p>This method removes a data source.</p><p class=\"callout-warning\">Currently, the default MongoDB data source cannot be deleted through this method.</p>",
"type": "Success",
"nickname": "removeDatasource",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified credentials cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The data source has been deleted."
}
],
"examples": [
{
"description": "The following request removes the MongoDB data source named <code>stackoverflow</code>.",
"title": "Removing a MongoDB data source",
"request": "curl -X DELETE http://myproject.28.io/v1/_datasources/MongoDB/stackoverflow?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"success\" : true\n}"
}
]
}
]
},
{
"path": "/_datasources/{category}/{datasource}/contents",
"description": "Data Source Content Management",
"operations": [
{
"method": "GET",
"summary": "List available collections",
"notes": "<p>This method retrieves the list of available collections from a data source.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "array",
"items": {
"$ref": "Collection"
},
"nickname": "getDatasourceContents",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source does not exist.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns available collections."
}
],
"examples": [
{
"title": "Listing available MongoDB collections",
"description": "The following request retrieves the list of available collections from a MongoDB data source.",
"request": "curl -X GET http://myproject.28.io/v1/_datasources/MongoDB/_default/contents?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n[ {\n \"name\" : \"conceptmaps\",\n \"nameLoc\" : \"conceptmaps\",\n \"type\" : \"structured-item()\",\n \"countItems\" : 1,\n \"countIndexes\" : 0\n}, {\n \"name\" : \"reportschemas\",\n \"nameLoc\" : \"reportschemas\",\n \"type\" : \"structured-item()\",\n \"countItems\" : 2,\n \"countIndexes\" : 0\n} ]"
}
]
},
{
"method": "POST",
"summary": "Creates collection",
"notes": "<p>This method creates a new collection within a data source.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "createCollection",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "name",
"description": "The name of the new collection.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source cannot be found.",
"responseModel": "Error"
},
{
"code": 409,
"message": "The specified collection already exists.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 201,
"message": "The collection has been created."
}
],
"examples": [
{
"title": "Creating a new MongoDB collection",
"description": "The following request creates a new MongoDB collection named <code>answers</code>.",
"request": "curl -X POST http://myproject.28.io/v1/_datasources/MongoDB/_default/contents?name=answers&token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 201 Created"
}
]
}
]
},
{
"path": "/_datasources/{category}/{datasource}/contents/{collection}",
"description": "Collection Management",
"operations": [
{
"method": "GET",
"summary": "Retrieves metadata about a collection",
"notes": "<p>This method retrieves the metadata of a collection.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Collection",
"nickname": "getCollectionMetadata",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source or collection cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns collection metadata."
}
],
"examples": [
{
"title": "Retrieving a MongoDB collection metadata",
"description": "The following request retrieves the metadata of the collection named <code>conceptmaps</code> in the <code>_default</code> MongoDB data source.",
"request": "curl -X GET http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/conceptmaps?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"name\" : \"conceptmaps\",\n \"nameLoc\" : \"conceptmaps\",\n \"type\" : \"structured-item()\",\n \"countItems\" : 1,\n \"countIndexes\" : 0\n}"
}
]
},
{
"method": "DELETE",
"summary": "Removes a collection",
"notes": "<p>This method removes a collection from a data source.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "removeCollection",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source or collection cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The collection has been deleted."
}
],
"examples": [
{
"title": "Removing a MongoDB collection",
"description": "The following request removes a collection named <code>answers</code> from the <code>_default</code> MongoDB data source.",
"request": "curl -X DELETE http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"success\" : true\n}"
}
]
}
]
},
{
"path": "/_datasources/{category}/{datasource}/contents/{collection}/items",
"description": "Item Management",
"operations": [
{
"method": "GET",
"summary": "Lists collection items",
"notes": "<p>This method retrieves a list of items a the collection.</p><p>The following serialization methods are available: <a href=\"http://jsoniq.org/docs/JSONiqExtensionToXQuery/html-single/#section-json-serialization\" target=\"_blank\">JSON-XML-hybrid</a>, <a href=\"http://jsoniq.org/docs/JSONiqExtensionToXQuery/html-single/#section-json-serialization\" target=\"_blank\">JSON</a>, <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#xml-output\" target=\"_blank\">XML</a>, <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#text-output\" target=\"_blank\">Text</a>, <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#html-output\" target=\"_blank\">HTML</a>, and <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#xhtml-output\" target=\"_blank\">XHTML</a>.</p><p>It is also possible to use the 28.io serialization method. The 28.io serialization produces a JSON object with metadata about the items in the collection. This serialization method format is unstable and will be documented as soon we are ready to commit to backward compatibility.</p><p>If the Accept header is specified and it contains at least one supported mime-type, the preferred supported mime-type is used to choose the serialization method, according to the following mapping: <ul><li><code>application/mixed-json-xml</code>: <a href=\"http://jsoniq.org/docs/JSONiqExtensionToXQuery/html-single/#section-json-serialization\" target=\"_blank\">JSON-XML-hybrid Serialization</a></li><li><code>application/json</code> or any mime-type which ends with <code>+json</code>: <a href=\"http://jsoniq.org/docs/JSONiqExtensionToXQuery/html-single/#section-json-serialization\" target=\"_blank\">JSON Serialization</a></li><li><code>text/xml</code>, <code>application/xml</code> or any mime-type which ends with <code>+xml</code>: <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#xml-output\" target=\"_blank\">XML Serialization</a></li><li><code>text/html</code>: <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#html-output\" target=\"_blank\">HTML Serialization</a></li><li><code>application/xhtml+xml</code>: <a href=\"http://www.w3.org/TR/xslt-xquery-serialization/#xhtml-output\" target=\"_blank\">XHTML Serialization</a></li><li><code>application/28io+json</code>: 28.io Serialization (format definition unstable)</li><li><code>* / *</code>: 28.io Serialization (format definition unstable).</li></ul>If the <code>Accept</code> header is not specified, the 28.io Serialization (format definition unstable) will be used. In case no charset has been specified in the <code>Accept</code> header, <code>UTF-8</code> is used. Otherwise, the specified charset is used.<p class=\"callout-warning\">Any mime-type not matching one of the conditions listed above is not supported by this resource.</p></p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "CollectionList28IO",
"produces": [
"*/*",
"application/xml",
"application/xhtml+xml",
"text/html",
"text/plain",
"application/json",
"application/28.io+json"
],
"_issues": "I cannot document the different return formats",
"nickname": "listCollection",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "offset",
"description": "The index of the first item from which to start listing the collection items. Default is 1.",
"required": false,
"type": "integer",
"minimum": 1,
"paramType": "query"
},
{
"name": "limit",
"description": "The number of collection items to list. Default is 10.",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 500,
"paramType": "query"
},
{
"name": "expand",
"description": "Whether to include the serialized item in the listing. The default value is false.",
"required": false,
"type": "boolean",
"paramType": "query"
},
{
"name": "Accept",
"paramType": "header",
"required": false,
"description": "Serialization format.",
"type": "string",
"enum": [
"application/28.io+json",
"application/mixed-json-xml",
"application/json",
"application/xml",
"text/html",
"application/xhtml+xml",
"text/plain"
]
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source or collection cannot be found.",
"responseModel": "Error"
},
{
"code": 406,
"message": "The collection content cannot be serialized as specified by the Accept header.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns collection metadata."
}
],
"examples": [
{
"title": "Listing items from a MongoDB collection",
"description": "The following request retrieves the items contained in a collection named <code>conceptmaps</code> from the <code>_default</code> MongoDB data source.",
"request": "curl -X GET http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/conceptmaps/items?offset=1&limit=10&token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 Ok\n{\n \"href\" : \"/v1/_datasources/MongoDB/_default/contents/conceptmaps/items?offset=1&limit=10\",\n \"offset\" : 1,\n \"limit\" : 10,\n \"count\" : 1,\n \"items\" : [ {\n \"href\" : \"/v1/_datasources/MongoDB/_default/contents/conceptmaps/items/5269bc91-d6f9b3d9-dba775de\",\n \"content\" : \"{\n \\\"_id\\\" : \\\"5269BC91D6F9B3D9DBA775DE\\\", \n \\\"name\\\" : \\\"FundamentalAccountingConcepts\\\", \n \\\"version\\\" : \\\"1.0\\\", \n \\\"namespaces\\\" : {\n \\\"fac\\\" : \\\"http://www.xbrlsite.com/2013/FundamentalAccountingConcepts\\\"\n }, \n \\\"mappings\\\" : {\n \\\"fac:Assets\\\" : [ \\\"us-gaap:Assets\\\", \\\"us-gaap:AssetsCurrent\\\" ]\n }\n}\",\n \"contentType\" : \"application/json\"\n} ]\n}"
}
]
},
{
"method": "POST",
"summary": "Inserts an item into a collection",
"notes": "<p>This method inserts an item into a data source collection.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "insertInCollection",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "item",
"description": "The item to insert.",
"required": true,
"type": "string",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source or collection cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 201,
"message": "The item has been created."
}
],
"examples": [
{
"title": "Inserting an item into a MongoDB collection",
"description": "The following request inserts a item into a collection named <code>answers</code> from the <code>_default</code> MongoDB data source.",
"request": "curl -H \"Content-Type: application/json; charset=utf-8\" -d \"{ \"answer\": 2 }\" -X POST http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers/items?offset=1&limit=10&token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 201 Created"
}
]
},
{
"method": "DELETE",
"summary": "Truncates a collection",
"notes": "<p>This method truncates a collection.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "truncateCollection",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source or collection cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The item has been removed."
}
],
"examples": [
{
"title": "Truncating a MongoDB collection",
"description": "The following request truncates a collection named <code>answers</code> which belongs to the <code>_default</code> MongoDB data source.",
"request": "curl -X DELETE http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers/items?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 Ok\n{\n \"success\" : true\n}"
}
]
}
]
},
{
"path": "/_datasources/{category}/{datasource}/contents/{collection}/items/{identifier}",
"operations": [
{
"method": "GET",
"summary": "Retrieves a collection item",
"notes": "<p>This method retrieves a collection item.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Item28IO",
"_issues": "No way of describing the other return formats",
"nickname": "getItem",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "identifier",
"description": "The item identifier.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source, collection or item cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "Returns the item."
}
],
"examples": [
{
"title": "Retrieving an item from a MongoDB collection",
"description": "The following request retrieves an item with <code>c5c28e20-4729-11e3-8f96-0800200c9a66</code> as reference identity from collection named <code>answers</code> which belongs to the <code>_default</code> MongoDB data source.",
"request": "curl -X GET http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers/items/c5c28e20-4729-11e3-8f96-0800200c9a66?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"_id\": \"c5c28e20-4729-11e3-8f96-0800200c9a66\",\n \"answer\": 42\n}"
}
]
},
{
"method": "PUT",
"summary": "Updates a collection item",
"notes": "<p>This method updates a collection item.</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "updateItem",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "identifier",
"description": "The item identifier.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
},
{
"name": "item",
"description": "The new item.",
"required": true,
"type": "string",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source, collection or item cannot be found.",
"responseModel": "Error"
},
{
"code": 409,
"message": "The specified item conflicts with existing data or the collection declaration.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The item has been updated."
}
],
"examples": [
{
"title": "Updating an item in a MongoDB collection",
"description": "The following request updates an item with the identifier <code>c5c28e20-4729-11e3-8f96-0800200c9a66</code> from collection named <code>answers</code> which belongs to the <code>_default</code> MongoDB data source.",
"request": "curl -H \"Content-Type: application/json; charset=utf-8\" -d \"{\n \"answer\": 43\n}\" -X PUT http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers/items/c5c28e20-4729-11e3-8f96-0800200c9a66?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"success\" : true\n}"
}
]
},
{
"method": "DELETE",
"summary": "Removes an item from a collection",
"notes": "<p>This method removes an item from a collection</p><p class=\"callout-warning\">Currently, this method is only available for MongoDB data sources.</p>",
"type": "Success",
"nickname": "removeItem",
"parameters": [
{
"name": "category",
"description": "The data source category.",
"required": true,
"type": "string",
"paramType": "path",
"enum": [
"MongoDB",
"JDBC",
"Cloudant",
"CloudSearch"
]
},
{
"name": "datasource",
"description": "The data source name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "collection",
"description": "The collection name.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "identifier",
"description": "The item identifier.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "token",
"description": "A project token.",
"required": true,
"type": "string",
"paramType": "query"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad request: a parameter is missing or invalid.",
"responseModel": "Error"
},
{
"code": 401,
"message": "Unauthorized: the specified project token is invalid or expired.",
"responseModel": "Error"
},
{
"code": 404,
"message": "The specified data source, collection or item cannot be found.",
"responseModel": "Error"
},
{
"code": 500,
"message": "An internal error occurred during the processing of the request.",
"responseModel": "Error"
}
],
"successMessages": [
{
"code": 200,
"message": "The item has been removed."
}
],
"examples": [
{
"title": "Removing an item from a MongoDB collection",
"description": "The following request removes an item with the idetifier named <code>c5c28e20-4729-11e3-8f96-0800200c9a66</code> from collection named <code>answers</code> which belongs to the <code>_default</code> MongoDB data source.",
"request": "curl -X DELETE http://myproject.28.io/v1/_datasources/MongoDB/_default/contents/answers/items/c5c28e20-4729-11e3-8f96-0800200c9a66?token=MUVSek1XU2c5aVJCeENRcUgyV2ZlbkFKbytnPToyMDEzLTExLTA2VDIwOjI2OjQ5LjgzNzMzNFo=",
"response": "< 200 OK\n{\n \"success\" : true\n}"
}
]
}
]
}
],
"models": {
"Success": {
"id": "Success",
"description": "Default success response",
"required": [
"success"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
"true"
]
}
}
},
"Error": {
"id": "Error",
"description": "Error information",
"required": [
"request_id",
"context",
"message",
"description"
],
"properties": {
"request_id": {
"type": "string",
"description": "The request identifier"
},
"context": {
"type": "string",
"description": "The complete domain name of the project"
},
"message": {
"type": "string",
"description": "A formatted string which contain the error code (always) and the module name, line and column-number and error description (when available)"
},
"type": {
"type": "string",
"description": "For XQuery errors, the type of the error (e.g. static)"
},
"code": {
"type": "string",
"description": "For XQuery errors, the error code"
},
"location": {
"type": "Location",
"description": "For XQuery errors, the error location (if available)"
},
"stack-trace": {
"type": "array",
"items": {
"$ref": "StackEntry"
},
"description": "For XQuery errors, the error stack trace (if available)"
}
}
},
"Location": {
"id": "Location",
"description": "Error information",
"required": [
"module",
"line-number",
"line-number-end",
"column-number",
"column-number-end"
],
"properties": {
"module": {
"type": "string",
"description": "The error module"
},
"line-number": {
"type": "string",
"description": "The error first line number"
},
"line-number-end": {
"type": "string",
"description": "The error last line number"
},
"column-number": {
"type": "string",
"description": "The error first column number"
},
"column-number-end": {
"type": "string",
"description": "The error last column number"
}
}
},
"StackEntry": {
"id": "StackEntry",
"description": "A stack entry",
"required": [
"function",
"location"
],
"properties": {
"function": {
"type": "Function",
"description": "The function of the call"
},
"type": {
"type": "Location",
"description": "The location of the call"
}
}
},
"Item28IO": {
"id": "Item28IO",
"description": "An item serialized using the 28io+json serialization method",
"required": [
"content"
],
"properties": {
"contentType": {
"type": "string",
"description": "The item content-type, if different from the default one"
},
"href": {
"type": "string",
"description": "A link that can be used to refer to the item. It is present only for items which are stored in a MongoDB collection"
},
"content": {
"type": "string",
"description": "The item serialized using the \"json+xml hybrid\" serialization method"
}
}
},
"CollectionList28IO": {
"id": "CollectionList28IO",
"description": "Collection listing in 28.io+json formt",
"required": [
"href",
"offset",
"limit",
"count",
"items"
],
"properties": {
"first": {
"type": "string",
"description": "The link to the first page of this collection item listing. Its offset is always 1, its limit is the same as the current request. It is present only if the the current offset is greater than 1"
},
"previous": {
"type": "string",
"description": "The link to the previous page of this collection item listing. Its offset is the maximum among 1 and the current offset minus the current limit. It is present only if the the current offset is greater than 1"
},
"href": {
"type": "string",
"description": "The link to this collection item listing, with the same offset and limit"
},
"next": {
"type": "string",
"description": "The link to the next page of this collection item listing. Its offset is the sum of the current offset and the current limit. It is present only if the last item contained in the response is not the last one in the collection"
},
"last": {
"type": "string",
"description": "The link to the last page of this collection item listing. Its offset is the biggest number smaller or equal to the number of items in the collection which can be obtained adding one or more times the current limit to the current offset. The limit is the same as the current page. It is present only if the last item contained in the response is not the last one in the collection"
},
"offset": {
"type": "integer",
"description": "The requested offset",
"minimum": "1"
},
"limit": {
"type": "integer",
"description": "The requested limit",
"minimum": "1",
"maximum": "500"
},
"count": {
"type": "integer",
"description": "The declared type of the items in the collection",
"minimum": "1"
},
"items": {
"type": "array",
"items": {
"$ref": "Item28IO"
},
"description": "The list of item starting whose position (starting from 1) in the collection is between offset(included) and offset+limit (excluded)"
}
}
}
}
}