From 6599d5181453c74b22c059d83b00daf161238cc8 Mon Sep 17 00:00:00 2001 From: Bartosz Kryza Date: Mon, 30 May 2016 15:43:59 +0200 Subject: [PATCH] Initial commit --- README.md | 7 ++++ build.sh | 17 +++++++++ definitions/index.yaml | 7 ++++ index.yaml | 8 ++++ info/index.yaml | 30 +++++++++++++++ paths/index.yaml | 8 ++++ resolve.js | 16 ++++++++ rest_api.mustache | 87 ++++++++++++++++++++++++++++++++++++++++++ rest_model.mustache | 34 +++++++++++++++++ 9 files changed, 214 insertions(+) create mode 100644 README.md create mode 100755 build.sh create mode 100644 definitions/index.yaml create mode 100644 index.yaml create mode 100644 info/index.yaml create mode 100644 paths/index.yaml create mode 100644 resolve.js create mode 100644 rest_api.mustache create mode 100644 rest_model.mustache diff --git a/README.md b/README.md new file mode 100644 index 0000000..2fca47f --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# Onepanel REST API defined using Swagger (http://swagger.io) + +This repo contains Swagger specification of Oneprovider REST API. + + +Compiling: +- Run ./build.sh from this directory and it should generate 'swagger.json' file \ No newline at end of file diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..242a03f --- /dev/null +++ b/build.sh @@ -0,0 +1,17 @@ +#!/bin/bash + +# Generate aggregate JSON file from YAML +docker run --rm -v `pwd`:/swagger docker.onedata.org/swagger-aggregator:1.4.0 + +# Validate the JSON +docker run --rm -v `pwd`:/swagger docker.onedata.org/swagger-cli:1.2.0 validate /swagger/swagger.json + +# Generate the Cowboy server stub +docker run --rm -v `pwd`:/swagger -t docker.onedata.org/swagger-codegen:1.2.0 generate -i ./swagger.json -l cowboy -o ./generated/cowboy + +# Generate C# stub to get all moustache tempalte keywords +#swagger-codegen-dbg generate -i ./swagger.json -l csharp -o ./generated/csharp -o tmp > model.json + +# Generate the static documentation +docker run --rm -v `pwd`:/swagger -t docker.onedata.org/swagger-bootprint:1.1.0 swagger ./swagger.json generated/static + diff --git a/definitions/index.yaml b/definitions/index.yaml new file mode 100644 index 0000000..36ce3b1 --- /dev/null +++ b/definitions/index.yaml @@ -0,0 +1,7 @@ +# +# This file groups the type definitions for Onezone REST API +# + +error: + $ref: ./error.yaml + diff --git a/index.yaml b/index.yaml new file mode 100644 index 0000000..3840b6f --- /dev/null +++ b/index.yaml @@ -0,0 +1,8 @@ +swagger: '2.0' +basePath: /api/v3/oneprovider +info: + $ref: ./info/index.yaml +paths: + $ref: ./paths/index.yaml +definitions: + $ref: ./definitions/index.yaml diff --git a/info/index.yaml b/info/index.yaml new file mode 100644 index 0000000..32827ab --- /dev/null +++ b/info/index.yaml @@ -0,0 +1,30 @@ +version: 3.0.0 +title: Onezone +description: | + This is the RESTful API definition of Oneprovider component of Onedata data management system [http://www.onedata.org]. + + This API provides methods for file management using REST protocol. + + ## Authentication + In order to be able to use this API the REST client must be able to authenticate with the Onezone service. + + Currently this is supported through authentication token which can be generate using the Onedata user interface. + The token must be added to the request header: + - TODO + + In addition please take into account, that depending on your account authorization rights, not all operations + may be possible. In particular, some operations depend on whether a particular request is initiated by a regular + user or by another storage provider within a zone. + + ## API structure + The Oneprovider API reflects the fact that most operations deal directly with virtual file paths relative to + user spaces, which are provided as part of the paths in the REST calls. + + +contact: + name: Onedata support + url: https://onedata.org/support + email: info@onedata.org +license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html \ No newline at end of file diff --git a/paths/index.yaml b/paths/index.yaml new file mode 100644 index 0000000..93a3599 --- /dev/null +++ b/paths/index.yaml @@ -0,0 +1,8 @@ +# +# This file groups path definitions for Onezone API +# defined in separate files for each path +# + + + + diff --git a/resolve.js b/resolve.js new file mode 100644 index 0000000..f6b2777 --- /dev/null +++ b/resolve.js @@ -0,0 +1,16 @@ +var resolve = require('json-refs').resolveRefs; +var YAML = require('yaml-js'); +var fs = require('fs'); + +var root = YAML.load(fs.readFileSync('index.yaml').toString()); +var options = { + filter : ['relative', 'remote'], + loaderOptions : { + processContent : function (res, callback) { + callback(null, YAML.load(res.text)); + } + } +}; +resolve(root, options).then(function (results) { + console.log(JSON.stringify(results.resolved, null, 2)); +}); diff --git a/rest_api.mustache b/rest_api.mustache new file mode 100644 index 0000000..26dda0e --- /dev/null +++ b/rest_api.mustache @@ -0,0 +1,87 @@ +-module(rest_api). + +-import(validator). +-import(rest_model). +-import(installer). +-import(installer_db). +-import(installer_worker). +-import(installer_cm). + +%%% +%%% {{appName}} +%%% +%%% {{appDescription}} +%%% Version: {{version}} + +%%% +%%% @doc Returns a Cowboy-understandable PathList of routes supported by a module +%%% implementing this behavior. +%%% @see rest_module_behavior +%%% @end +%%% +-spec routes() -> + [{PathMatch :: binary(), rest_handler, State :: rstate()}]. +routes() -> + S = #rstate{module = ?MODULE, root = spaces}, + M = rest_handler, + [ +{{#operations}} +{{#operation}} + { <<"{{basePathWithoutHost}}{{path}}">>, {{operationId}}, S#rstate{resource = hosts, method = '{{httpMethod}}' }{{#hasMore}},{{/hasMore}} +{{/operation}} +{{/operations}} + ]. + + +{{#operations}} +{{#operation}} +%%% +%%% '{{basePathWithoutHost}}{{path}}' +%%% @doc {{notes}} +%%% +%%% HTTP method: {{httpMethod}} +%%% +{{#allParams}} +%%% @param {{paramName}} {{description}} +{{/allParams}} +%%% +-{{operationId}}({{#allParams}}{{dataType}} :: {{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}}) -> + {{#hasPathParams}} + % + % Validate path params - in case of array parameters in path they need to be parsed + % by parsing a comma-separated list + % + {{#pathParams}} + {{#isContainer}} + Param_{{paramName}} = validator:parse('csv', {{paramName}}), + {{/isContainer}} + {{^isContainer}} + Param_{{paramName}} = validator:parse('string', {{paramName}}), + {{/isContainer}} + {{/pathParams}} + {{/hasPathParams}} + {{#hasConsumes}} + {{#hasBodyParams}} + % + % Validate the input body params + % + {{/hasBodyParams}} + {{#bodyParams}} + Param_{{paramName}} = validator:parse('{{consumes.0.mediaType}}', {{paramName}}, rest_model:{{dataType}}_schema()), + {{/bodyParams}} + {{/hasConsumes}} + {{#hasQueryParams}} + % + % Validate query params + % + {{#queryParams}} + Param_{{paramName}} = validator:parse('{{dataType}}', {{paramName}}), + {{/queryParams}} + {{/hasQueryParams}} + % + % Call the appropriate function handler in specific module + % + {{#vendorExtensions}}{{x-onedata-module}}{{/vendorExtensions}}:{{#vendorExtensions}}{{x-onedata-method}}{{/vendorExtensions}}(#{ {{#allParams}}"{{paramName}}" => Param_{{paramName}} {{#hasMore}},{{/hasMore}}{{/allParams}} }). + +{{/operation}} +{{/operations}} diff --git a/rest_model.mustache b/rest_model.mustache new file mode 100644 index 0000000..97ce3a9 --- /dev/null +++ b/rest_model.mustache @@ -0,0 +1,34 @@ +-module(rest_model). + +% +% Definitions of records for REST API +% + + +{{#models}} +{{#model}} +% +% {{classname}} +% +% {{description}} +% +-record({{classname}}, { +{{#vars}} + % {{description}} + {{name}} :: {{datatype}}(), +{{/vars}} }). + +% +% Record schema for validation of JSON strings received via REST API. +% +-{{classname}}_schema() -> + #{ + {{#vars}} + <<"{{name}}">> => { {{datatypeWithEnum}}, {{#required}}true{{/required}}{{^required}}false{{/required}} }, + {{/vars}} + } + . + + +{{/model}} +{{/models}}