Initial commit

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

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
+

definitions/index.yaml

@@ -0,0 +1,7 @@
+#
+# This file groups the type definitions for Onezone REST API
+#
+
+error:
+  $ref: ./error.yaml
+

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

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: [email protected]
+license:
+  name: Apache 2.0
+  url: http://www.apache.org/licenses/LICENSE-2.0.html

paths/index.yaml

@@ -0,0 +1,8 @@
+#
+# This file groups path definitions for Onezone API
+# defined in separate files for each path
+#
+
+
+
+

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));
+});

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}}

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}}