# # Webida Restful Api specifiaion # # Current api desingn rules # 1) Any (and only) "reusable" schemas should be placed in #/parameters, #/definitions # 2) Do not use multiple tags in a single operaion to reduce client code size # 3) All "real-path" parameters (can contain /) should be "relative". # An operation can have 0 or 1 real-path parameters, at the end of path params. # 4) Prefer /some-name-plural/{id} form (except wfs) and don"t mix with sigular noun # 5) All response should be an object or file. No Plain Text! # 6) Keep common/starndard http status code semantic, as possible as we can. # 7) Do not split this document into pieces, for none of standard swagger tools supoorts # multi-docs spec yet. # 8) Do not use "polymorphism" with discriminator property. swagger-codegen for JS does # not support such polymorphism yet. # notes for swaggerize-routes # - 1 x-handler impl module for every operation. file name should be same to operation id. swagger: "2.0" info: version: "0.7.1" title: Webida Restful API description: Restful API for Webida clients to use server's data & features license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html # Should not include host / schemes in this spec when publishing, # for server/client implementations 'ALWAYS' tend to override the value to current # service url. basePath: /api produces: - application/json - application/octet-stream consumes: - application/json paths: /auth/login: post: x-handler: handlers/auth/login.js tags: ["auth"] description: | A "VERY" basic authentication, required to use webida-simple-auth security scheme. Service / Product implementations who need better security, should override this operation or add their own login api or some other specs like OAuth2. Simple auth is not suitable for large-sacle, multi-tennant service, for the scheme assumes a single, trusted user only. Logging-in with master token, the generated access token inherits all restriction from it. On the other hand, normal log-in with login id & password creates an unrestricted access token, with reasonably short expiration time. Every client should spawn another access token with issueToken API before current access token expires, inheriting session id from current token. To save remote access info, client should create a (restricted but long-ttl) master token to start IDE from remote. The remote client should not use the unrestricted acccess token from login to use any other perpose than finding available workspaces, and should not refresh the token. (Let user log-in again) Login API does not force any encryption. Server should provide secure transport channel, usually https, to provide remote access, always. operationId: login parameters: - name: body in: body required: true schema: $ref: "#/definitions/Credential" responses: "200": description: login success schema: $ref: "#/definitions/Token" default: description: Error schema: $ref: "#/definitions/RestError" /auth/info: get: x-handler: handlers/auth/getInfo.js tags: ["auth"] description: | Gets user information of that can be identified with current access token. Implementations should provide a more restful api based on domain data model, not extending this operation. (e.g. GET,PUT and DELETE on /Users/{userId} to read, update and delete user) operationId: getInfo security: - webida-simple-auth: [] responses: "200": description: user information schema: $ref: "#/definitions/User" "401": description: auth failed schema: $ref: "#/definitions/RestError" default: description: Error schema: $ref: "#/definitions/RestError" /auth/token: post: x-handler: handlers/auth/issueToken.js tags: ["auth"] description: | Creates new token from current access token, inheriting workspace id & session id. The duration of generated token is not (and should not be) parameterizable. Server should set proper duration, respecting "reconnect" period of socket.io clients. Remember that most of socket.io client implementations (including official js client) do not provide any ways to change connection parameters (header or query) while reconnecting to server. Like login API, this endpoint does not provide any encryption. Server should not set any data to harm security in the token & should provide some signinig/encryption mechanism to protect token. Simple JSON Web Token with HMAC-SHA will do. operationId: issueToken security: - webida-simple-auth: [] parameters: - name: type in: query required: true type: string enum: ["MASTER", "ACCESS"] - name: workspaceId in: query required: false type: string description: Clients to save some remote access info should issue a MASTER type token restricted to specific workspace id. responses: "200": description: new token generated schema: $ref: "#/definitions/Token" default: description: Error schema: $ref: "#/definitions/RestError" # Basic WFS operations , read/write file, create dir, delete, copy, move, ... # wfs paths starts with /wfs/{wfsId} # /file/{wfsPath} file CRUD C,U is PUT, not POST # GET - read file # PUT - write file # /dir/{wfsPath} directory CRUD # GET - list (tree) dir # PUT - create (can be expanded to import, later) # /any/{wfsPath} # GET?{ignoreError} - stat / exists # PUT?{src} - copy # POST?{src} - move # DELETE - remove # /ops/search?{wfsPathQuery} for search (GET) and replace (POST) # /ops/replace?{wfsPathQuery} for search (GET) and replace (POST) # WFS File operations - read/write /wfs/{wfsId}/file/{wfsPath}: # readFile. get: x-handler: handlers/wfs/readFile.js tags: ["wfs"] description: read file data on path operationId: readFile security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - name: If-Modified-Since in: header required: false description: Usual if-modified-since header. So, should be RFC-1123(same to RFC-822) format, not RFC-3339 (same to ISO-8601). type: string - name: If-None-Match in: header required: false description: Usual if-non-match header, allowing only 1 e-tag value from previous readFile response. The value of this header can have weak prefix and quotation chars. This header value precedes the value of if-modified-since header. Server should ignore if-modified-since header when if-none-match header exists, as RFC-2616. type: string responses: "200": description: File contents. Content-Type is application/octet-stream or follows file name extension. schema: type: file headers: ETag: description: usual etag header in HTTP 1.1 type: string Last-Modified: description: usual last-modified header, in RFC-1123 format. type: integer default: description: Error schema: $ref: "#/definitions/RestError" # writeFile put: x-handler: handlers/wfs/writeFile.js tags: ["wfs"] description: Creates / updates file with body data. Server should write the file in atomic manner nd should not write down request body into final destination path directly. In other words, wheather writeFile() succeeds or not, the contents of the file should not be corrupted nor half-written. operationId: writeFile consumes: - multipart/form-data security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - $ref: "#/parameters/ensureParents" - name: data in: formData required: true description: file contents to write. type: file responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # WFS Dir operations - list(tree) and create empty one /wfs/{wfsId}/dir/{wfsPath}: # dirTree get: x-handler: handlers/wfs/dirTree.js tags: ["wfs"] description: Returns a directory tree of given path, the errors while building sub-tree will be ignored and result will not include the path that has errors. Client may have to stat some suspicious paths manually, if listing is not complete. operationId: dirTree security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - name: maxDepth description: Maximum depth of tree. -1 to build a full tree, 0 to stat, 1 to plain list. in: query type: integer required: true responses: "200": description: A DirEntry, root of the tree, for given path and depth. schema: $ref: "#/definitions/DirEntry" default: description: Error schema: $ref: "#/definitions/RestError" # createDir put: x-handler: handlers/wfs/createDir.js tags: ["wfs"] description: Creates a directory at the path. When the path is found to be a directory, this api does not return error and does not care it's empty or not. Always creates parent directories if needed. operationId: createDir security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # WFS Any operations - stat & exist, copy, move, remove /wfs/{wfsId}/any/{wfsPath}: # stat get: x-handler: handlers/wfs/stat.js tags: ["wfs"] description: Get stats of given path. (stat() returns stats object in node and POSIX system). This API should be called only when stats of some file system path is stale for unknown reason (e.g. losting change events). Use dirTree operation and session events to detect stats, if possible. This API can be used to check a path is valid, existing one, but it's not recommended to check existence of individual paths by API. Clients should use dirTree and session events to synchorize some in-app file system with webida file system. operationId: stat security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - name: dummyFor404 in: query required: false description: When true, operation ignore ENOENT error and returns DUMMY stats object instead of 404 error. type: boolean default: false responses: "200": description: stats object. schema: $ref: "#/definitions/Stats" default: description: Error schema: $ref: "#/definitions/RestError" # copy put: x-handler: handlers/wfs/copy.js tags: ["wfs"] description: | Creates a copy of source to given path. Unlike cp command, wfsPath always denotes an exact path of the resource to be created. So, When destination path exists already, 1) copying file to file : follows noOverwrite flag. (does not return error) 2) copying file to dir : returns 409 error 3) copying dir to file : returns 409 error 4) copying dir to dir : merge srcPath/* to wfsPath, following noOverwite flag. This operation creates the parents dir of destination path always, and does not roll-back the creation when operation failed. So, clients should roll-back if needed. operationId: copy security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - $ref: "#/parameters/srcPath" - $ref: "#/parameters/noOverwrite" - name: followSymbolicLinks in: query description: dereference symlinks in source. required: false type: boolean default: false - name: preserveTimestamps in: query description: keep mtime/atime of source file(s) in destination. required: false type: boolean default: false responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # move post: x-handler: handlers/wfs/move.js tags: ["wfs"] description: Moves source resource to given path. Follows same rule to deal with existing path. So, this operation works like rename rather than mv. Just like copy(), this operations creates paraent dirs if needed and does not roll-back. Symbolic link and timestamp values will be moved without touching. operationId: move security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - $ref: "#/parameters/srcPath" - $ref: "#/parameters/noOverwrite" responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # remove / delete delete: x-handler: handlers/wfs/remove.js tags: ["wfs"] description: delete file or directory operationId: remove security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPath" - name: noRecursive in: query required: false description: if set, deleting non-empty directory will return 409 error. type: boolean default: false responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # WFS search operation /wfs/{wfsId}/ops/search: get: x-handler: handlers/wfs/search.js tags: ["wfs"] description: search files in some path, with given pattern operationId: search security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPathList" - $ref: "#/parameters/pattern" - $ref: "#/parameters/ignoreCase" responses: "200": description: search schema: type: object additionalProperties: type: array items: $ref: "#/definitions/Match" default: description: Error schema: $ref: "#/definitions/RestError" # WFS replace operation /wfs/{wfsId}/ops/replace: post: x-handler: handlers/wfs/replace.js tags: ["wfs"] description: replace file contents with regex matching operationId: replace security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/wfsId" - $ref: "#/parameters/wfsPathList" - $ref: "#/parameters/pattern" - $ref: "#/parameters/ignoreCase" - name: replaceTo in: query description: string to replace with type: string required: true responses: "200": description: done schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # workspace management operations # workspaces/{workspaceId} - individual local workspaces # GET : find workspaces # POST: create workspace # PUT : update single workspace # DELETE : delete single workspace /workspaces/{workspaceId}: # findWorkspaces get: x-handler: handlers/workspace/findWorkspaces.js tags: ["workspace"] description: | Finds workspaces with given id or parameters. if workspaceId = '*', all workspaces in server are returned. No empty workspace id is allowed for it's a path parameter. When workspaceId is not '*', server should return empty array, not 404 Not Found error. operationId: findWorkspaces security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - name: includeEphemeral in: query required: false description: flag to include ephemeral workspaces or not, when workspaceId is '*'. if workspace id is specified, then this flag will be ignored. type: boolean default: false responses: "200": description: array of local workspaces found schema: type: array items: $ref: "#/definitions/Workspace" default: description: Error schema: $ref: "#/definitions/RestError" # createWorkspace post: x-handler: handlers/workspace/createWorkspace.js tags: ["workspace"] description: | Creates a new workspace with given local path. Requires an unrestricted access token. the workspace id parameter is ignored and will be replaced by new, unique value by server. it's recommended to set the value to simple, bogus one, like '*' or '-' (since it's path parameter, empty value is not allowed. excludedPath property is initialized with default values (usually .git/, .node_modules/, ./bower_components) by server. Needs an unrestricted access token. operationId: createWorkspace security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - name: localPath in: query required: true description: a real, local path of the system (not unixified) type: string - name: name in: query required: true description: workspace name property type: string - name: description in: query required: true description: workspace name property type: string responses: "200": description: newly created local workspace schema: $ref: "#/definitions/Workspace" default: description: Error schema: $ref: "#/definitions/RestError" # update workspace put: x-handler: handlers/workspace/updateWorkspace.js tags: ["workspace"] description: | Updates workspace. Some protected properties will not be changed by this op. If server cannot apply changed properties before returning workspace, such properties should not be updated with this operation. Clients should not rely on request body for further works, and should always check response to see what's changed actually. Requires proper access rights. operationId: updateWorkspace security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - name: body in: body description: workspace object that contains updates required: true schema: $ref: "#/definitions/Workspace" responses: "200": description: updated Workspace object. some properties may different from input. schema: $ref: "#/definitions/Workspace" default: description: Error schema: $ref: "#/definitions/RestError" # delete workspace delete: x-handler: handlers/workspace/removeWorkspace.js tags: ["workspace"] description: | Removes a workspace. If no sessions are connected, this api 'works' before returning result. if some sesions are, workspace will be removed when 1) all sessions are closed for request (will be notified by server) 2) exceeded time limit value in closeAfter parameter 3) server stops after accepting remove request and willBeRemoved value is set. So, client may 'find' the workspace to be removed after calling this operation. Requires "unrestricted" access rights. operationId: removeWorkspace security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - name: closeAfter in: query description: Time in seconds to wait for all sessions save & close their data. type: integer required: false default: 0 - name: removeDir in: query description: flag to delete directory in real file system when removing workspace. Usually, this value should not be set true for user can handle directory persistence manually. Clients need to get explicit confirmation from user. type: boolean required: false responses: "200": description: OK. removed schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # workspace - exec operations # workspaces/{workspaceId}/exec # GET : findProcs # POST: exec # DELETE : cancel (for async exec only) /workspaces/{workspaceId}/procs: #findProcs get: x-handler: handlers/workspace/findProcs.js tags: ["workspace"] description: | Gets process info on this workspace. To find all child processes, set id to '*'. This op does not returns error when no procs found but empty result array. Child process can be created by exec operation and by some other means. operationId: findProcs parameters: - $ref: "#/parameters/workspaceId" - $ref: "#/parameters/execId" - name: includeForeground in: query description: flag to include 'foreground processes' in result. foreground processes can be created by and only by exec operation without async opetion. normally, this flag will not be used except debugging or diagnostics. foreground processes has 'foreground' property, set to true, always. type: boolean required: false responses: "200": description: the child processes found. result does not include 'exited' procs. schema: type: array items: $ref: "#/definitions/ChildProcess" default: description: Error schema: $ref: "#/definitions/RestError" #exec post: x-handler: handlers/workspace/execute.js tags: ["workspace"] description: Executes a shell command (foreground process) or spawns a background process on this workspace. Requires proper access rights. operationId: execute security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - name: async in: query description: Spawns a background process for given command and returns the created child proc info. Actual output (stream of message) will be delivered to web socket channel, using execution id. type: boolean required: false default: false - name: body in: body description: the process to be executed or spawned. required: true schema: $ref: "#/definitions/Execution" responses: "200": description: Execution result with all captured standard ouput and error. If execution is completed without error, the error property in result object should be a falsy value. If some error has happened, then it will be an error message, without stack. A plain RestError will be returned with 4xx or 5xx error code (e.g. insufficient/invalid arguments) when it's found before creating process. So, clients should handle the 'invocation error' and 'errors from the command' differently. schema: $ref: "#/definitions/ExecutionResult" "201": description: Spawned process infomation created by async execution. If server could not create a child process, error event will be sent to client via socket channel but RestError will not be ruturned from this operation. When a client has got 'error' event from the socket channel, the client should close the channel wheather it receives subsequent exit event or not (with some proper timeout if needed). Server should not send the errors related to 'killing' child processes. schema: $ref: '#/definitions/ChildProcess' default: description: Error schema: $ref: "#/definitions/RestError" #cancel delete: tags: ["workspace"] description: Cancels executions, killing the spawned processes. To terminate all spawned processes, set execId to '*'. Requires proper access rights. Since killing a process usually takes a little bit long time, this api does not returns actual result but works in async manner. (So, client should listen to web socket channels for the processes). This operation Requires same access rights to execute operation. Server should reject to cancel any forground processes and processes is being killed or has exited already. operationId: cancel security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/workspaceId" - $ref: "#/parameters/execId" responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # remote-access operations # GET : get all remote workspaces" access info, registered to local server # PUT : put (upsert) a remote workspace access info # DELETE : delete single remote workspace" access info /remotes: # findRemoteAccess get: x-handler: handlers/remotes/findRemoteAccesses.js tags: ["remotes"] description: Get all access informations See RemoteWorkspaceAccess definition for details (no fancy find / search feature yet) operationId: findRemoteAccesses security: - webida-simple-auth: [] responses: "200": description: Array of remote workspaces schema: type: array items: $ref: "#/definitions/RemoteAccess" default: description: Error schema: $ref: "#/definitions/RestError" # putRemoteAccess put: tags: ["remotes"] description: Ceates or updates a remote workspace access information operationId: putRemoteAccess security: - webida-simple-auth: [] parameters: - name: body in: body required: true schema: $ref: "#/definitions/RemoteAccess" responses: "200": description: OK schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # removeRemoteWorkspace delete: tags: ["remotes"] description: Removes remote workspace access information operationId: removeRemoteAccess security: - webida-simple-auth: [] parameters: - name: workspaceId in: query required: true description: workspace Id of remote workspace type: string responses: "200": description: removed remote workspace access info schema: $ref: "#/definitions/RemoteAccess" default: description: Error schema: $ref: "#/definitions/RestError" # session management operations # GET : find session # DELETE: close session /sessions/{sessionId}: # findSessions get: x-handler: handlers/session/findSessions.js tags: ["session"] description: | Finds webida sessions established to server. if session id is given, matched session info will be returned and workspace id parameter will be ignored. To find all sessions of some workspace, set session id to '*' and specify workspace id. This operation requires proper accsss rights. 1) To find all sessions, an unrestricted token is required. 2) To find some workspace sesions, token should have proper access right on the workspace. operationId: findSessions security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/sessionId" - $ref: "#/parameters/workspaceIdQuery" responses: "200": description: array of sessions schema: type: array items: $ref: "#/definitions/Session" default: description: Error schema: $ref: "#/definitions/RestError" # closeSessions delete: x-handler: handlers/session/closeSession.js tags: ["session"] description: Closes session with timeout. Targets are selected by same rule to findSessions() op. While targeting multiple sessions, this operation requires same access rights with findSessions(). Closing a single session requires 'same session id' or 'unrestricted workspace acceess'. operationId: closeSessions security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/sessionId" - $ref: "#/parameters/workspaceIdQuery" - name: closeAfter in: query type: integer description: | Waiting time before actual closing, to let client save files and prevent reconnecting. required: true responses: "200": description: OK. schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # no POST or PUT, for session should be created or updated by web-socket /aliass/{aliasId}: # findAliases get: x-handler: handlers/alias/findAliasesjs tags: ["alias"] description: get alias objects. set aliasId to '*' to find all aliases in some workspace. If alias id is given, only 0 or 1 matched alias object will be returned, ignoring workspaceId and srcPath. To get an alias object of some wfs path, set srcPath value to some path, and to find all aliases in a workspace, set it to '*' (empty value is not allowed by definition) operationId: findAliases security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/aliasId" - $ref: "#/parameters/workspaceIdQuery" - $ref: "#/parameters/srcPath" responses: "200": description: alias list schema: type: array items: $ref: "#/definitions/Alias" default: description: Error schema: $ref: "#/definitions/RestError" # putAlias put: x-handler: handlers/alias/putAlias.js tags: ["alias"] description: create, or update an alias. operationId: putAlias security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/aliasId" - name: body in: body description: alias object to write. should have same id to aliasId parameter. required: true schema: $ref: "#/definitions/Alias" responses: "200": description: OK. schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" # removeAliases delete: x-handler: handlers/alias/removeAlias.js tags: ["alias"] description: remove alias. targeting rule is same to findAliases() operation. operationId: removeAliases security: - webida-simple-auth: [] parameters: - $ref: "#/parameters/aliasId" - $ref: "#/parameters/workspaceIdQuery" - $ref: "#/parameters/srcPath" responses: "200": description: OK. schema: $ref: "#/definitions/RestOK" default: description: Error schema: $ref: "#/definitions/RestError" securityDefinitions: webida-simple-auth: type: apiKey name: Authorization in: header x-authorize: webida-simple-auth.js parameters: wfsId: name: wfsId in: path description: webida file system id (same to workspace id) to access. required: true type: string wfsPath: name: wfsPath in: path description: webida file system path to access. without heading /. should be placed at the end of path arguments required: true type: string pattern: .* srcPath: name: srcPath in: query description: source data path of some operations, without have heading / required: true type: string wfsPathList: name: wfsPathList in: query description: array of wfsPath, without heading /. required: true type: array items: type: string collectionFormat: multi ensureParents: name: ensureParents in: query description: A flag to create all parent directories to create file or dir, like mkdir -p. This parameter does not create entire path, but ensures 'parent directory' of the wfsPath parameter type: boolean required: false default: false noOverwrite: name: noOverwrite in: query description: does not overwrites any existing file while copying or moving required: false type: boolean default: false pattern: name: pattern in: query description: regex pattern to match in search or replace. In replace operation, pattern should be same to the parttern in search operation type: string required: true ignoreCase: name: ignoreCase in: query description: regex matching option to ignore case. In replace operation, this option should be same to one used in search operation type: boolean required: false default: false workspaceId: name: workspaceId in: path description: webida workspace id (usually same to file system id, wfsId) required: true type: string workspaceIdQuery: name: workspaceId in: query description: webida workspace id in query part required: true type: string execId: name: execId in: query description: the id from execution request (different from pid!) type: string required: true sessionId: name: sessionId in: path description: webida session id (usually different from socket id from sock.io) required: true type: string aliasId: name: aliasId in: path description: url path fragment alias id. should have no '/' as well as any 'unsafe' chars for url path. especially, '*' is reserved for finding operations or some other special case. required: true type: string definitions: RestOK: type: object properties: message: description: additional text from server. Clients may use this value to debugging or logging, but should not rely on the value of this property, for server can omit to set message for performance. type: string RestError: type: object description: Error object with code and message. code is bound to status code, but not always same to standard HTTP status text. For example, some 409 error may have code "Invalid Argument" instead of "Conflic". So, Client should read message property to know what happend exactly, when an error is returned from server. And, some 500 errors can have system errno instead of useless "internal". Like other errors, details are hidden in message. properties: code: type: string message: type: string errno: description: errno code for some internal errors in server. Since service implementation can use many different platform api & runtime, client should avoid relying on errno code. If server provides errno code, it should be translated into human readable string like ENOENT or ENOMEM, not pure integer value. type: string stack: description: stack trace for this error. Server should not include stack trace in production and client should not print or show this stack to user. This property should be used in 'developer mode' only, for debugging. type: string required: - message Token: type: object description: a json webtoken and accessible data properties: text: type: string description: actual token text that should be shipped in header or query tokenType: type: string enum: ["MASTER", "ACCESS"] description: | MASTER : used to create an access token from clients, without login credential ACCESS : protects api access. should be unique for each ide session Note that here"s no REFRESH token, nor LOGIN token. The login api will create unrestricted access token & master token pair. Desktop app has a side-way to create an unrestricted master token before starting IDE instances. expiresAt: type: string format: date-time issuedAt: type: string format: date-time sessionId: type: string description: mandatory for ACCESS token, identifying client instance workspaceId: type: string description: If truthy, access rights are restricted to specified workspace only. required: - text - tokenType - expiresAt - issuedAt Credential: type: object description: User credential to login. Use https to protect credential. master token can replace actual id/password pair. properties: loginId: type: string loginPassword: type: string masterToken: type: string description: A master token is issued when user wants to access webida api without id/password from remote or local desktop app. When masterToken is set, client should put some bogus id/password for login, non-empty. the values can be used to identify client type. required: - loginId - loginPassword User: type: object description: Any services/products should define some admin apis to manage users in the system and expose what should be exposed to client app. So, no properties are mandatory. Currently, the properties are defined for compatiblity with legacy clients. properties: id: type: string description: unique id per user (email is also unique) email: type: string name: type: string Stats: type: object description: simplified/augmented fs.Stats class - see node.js doc for all properties required: - type - birthtime - mtime - mode - size - nlink properties: type: type: string enum: - "FILE" - "DIRECTORY" - "BLOCK_DEVICE" - "CHARACTER_DEVICE" - "LINK" - "FIFO" - "SOCKET" - "DUMMY" description: All types except 'DUMMY' come from fs.Stats is*** methods results. (e.g. if isFile() is true, then type will be 'FILE') If type is not decidable by the methods, default type is 'FILE', for everything on the file system is basically a file. 'DUMMY' type means that some object 'does not exist for now'. Client may use 'DUMMY' type to mark something dangling, not written or created on real file system yet but visible to user. birthtime: type: string format: date-time mtime: type: string format: date-time mode: type: integer size: type: integer nlink: type: integer DirEntry: type: object description: a directory entry (file or directory) with children that represents a (sub) tree required: - name - stats - children properties: name: type: string stats: $ref: "#/definitions/Stats" children: type: array items: $ref: "#/definitions/DirEntry" Match: type: object description: search result for a file required: - line - text properties: line: type: integer text: type: string Workspace: type: object description: A workspace in server properties: id: description: the id of a workspace. usually same to file system id type: string name: description: display text of this workspace for UI type: string description: description: human readable description on this workspace type: string createdAt: description: the time when this workspace is created (registered from local file system) type: string format: date-time accessedAt: description: the time when the last session on this workspace was made. (optional) type: string format: date-time workspacePath: description: absolute path of this workspace in server. Server may not expose this property to some untrusted clients. type: string ephemeral: description: | If set, workspace is ephemeral - Server will drop registration when it stops working. Ususally, side-loaded workspace via desktop app is ephemeral. Client with proper access right can flip this flag to declare the workspace should be persist, after rebooting. type: boolean excludedPaths: description: | Ignore patterns to exclude from watch service and search-and-replace operations. Pattern follows '.gitignore' syntax, 1 item per line. It should work as a .gitignore file in the workspace directory. Server should remove all comment items (any item that begins with '#') and blank items. Escaping with '\' char for the beginning '!' and ending white-spaces shoule be supported, too. To exclude a directory, client may have to put '/' at the end of the item to exclude everything underneath it. When a dir path is excluded with 'ending /', watch service may not deliver unlinkDir/addDir events for the path and client should manually check the existence or stats. type: array items: type: string offlineCachePaths: description: | Any paths (including excluded paths) to be cached in remote clients. Browser client should respect offline cache paths always. Desktop-app client may not use off-line cache for local (embedded) server but shall use cache for any remote servers, even for same host. All caches should be partitioned with workspace id, globally unique value through time and space. Client should pre-fetch the contents of offline cache paths when it start IDE sessions on a workspace to use for off-line state. When client goes to off-line, after losing connection to server, it can use cached data as reply of some WFS operations and can write some data to cache to save workspace data & metadata. The changes should be persistent on client side safely. C When a client recovers connectivity to server, it should check the stats of files and dirs to upload if it has got some changes in offline state. If server has more recents contents, client should drop chagnes and refill the cache with fresher data. Client may have some 'time-tolerance' to accept server's data is fresher than client's, smaller than serveral seconds. If server has more recent contents, client should drop the changes and refill the cache with fresher data. If not, client should replay the changes 1 by 1. Same protocol should be applied when client application starts with some 'unuploaded change' evertime. That means, client should save 'change history' with 'changed data' too, to process it later, when starting app again in normal condition. All Clients should not replay any 'delete' operations while replaying changes on client's cache, to protect from more serious problems with skewed timer or unexpected behaviors. And, of course, client should not rely on cached data while connection state is healthy. type: array items: type: string required: - id - name - description - createdAt - workspacePath - excludedPaths - offlineCachePaths RemoteAccess: type: object description: Access information of remote workspace in remote server properties: name: description: display text of remote workspace. can be different from original name. type: string serverUrl: description: the url of remote server. Should have no path/query parameters, even "/" in path. type: string workspaceId: description: the id of remote workspace, read from remote server type: string workspacePath: description: Full path of remote workspace, read from remote server. this property will be removed when clients are able to work without "named root directory" in workspace fs tree. type: string masterToken: description: master token to access service, issued from remote server type: string required: - name - serverUrl - workspaceId - masterToken Session: type: object description: an application session per ide instance. bound to access token properties: id: description: the id of a session. usually same to socket id. type: string name: description: human readable name, usually derived from workspace name. type: string state: description: | NORMAL = connected, normally working. CLOSING = server requested client to disconnect. Connection will be closed soon. TERMINATED = disconnected. server will remove this session from registry ASAP. type: string enum: - NORMAL - CLOSING - TERMINATED workspaceId: description: the id of workspace that this sessions is working on. If falsy, then this session is not belonged to any workpsace. Usually, dashboard / monitoring app will create a session without workspace id. type: string clientAddress: description: the peer address of session connection. not always type: string connectedAt: description: the time when socket connection is established type: string format: date-time willCloseAt: description: when state becomes CLOSING, server sets this time as deadline. type: string format: date-time required: - id - name - state - clientAddress - connectedAt Execution: type: object description: | execution request, simlilar to node.js exec()/spawn(). see node.js documentation for details of each properties. some properties are not configurable for portability * encoding : fixed to utf-8 * shell : fixed to system defaults. (so, cmd.exe will be invoked in Windows OS, not sh or bash in git-for-windows even they are available.) * killSignal : fixed to SIGTERM. If process does not die, server can send SIGKILL or invoke taskkill, to ensure chlid process is killed. * uid & gid : will not be set for security * stdio : all streams are handled by server. no options are avaliable to client. * detached : always false properties: id: description: unique identifier of execution, to demux response stream or cancel request. Server should reject an async exec request without id. type: string command: description: The command to run. Server may not support pipe, redirection nor shell variables in command. Client should not assume any specific shell provider in server and should not using the shell features for portability. In windows system with unix sh (e.g. cygwin or mingw from git-for-windows), usually a shell script in PATH may work as command but probably allocates console window while running the command. Implementations (both of server & client) should avoid allocating any console instances while running services, for costs and UX, and should provide a portable way to invoke commands. Shortly, when a service/product embeds some .sh file to run, it must provide .cmd file doing same thing, always. type: string args: description: | The arguments array. Server can join this args to command with proper white-space char, when underlying platform api (e.g. child_process#exec() in node.js) does not support additional arguments vector. It's recommended to use args vector than making a long command, to find & see child processes easily with this Rest API. So, args should be always provided, even empty array. When some arguments has a white space (e.g. C:\Program Files\webida), usually invoking command understands escaping or quotation, but not always. Client should add proper escaping or quotation chars to args vector manually. server should not change any command or arguments. type: array items: type: string cwd: description: Current working directory of spawned process, relative to workspace root. If abscent, cwd will be the workspace directory. Does not accept any evaluatable form like $HOME, %USERPROFILE%. path should be unixified. Server may reject an absolute cwd path. type: string timeout: description: The value which In 'miliseconds' the maximum amount of time the child is allowed to run. (not idle time of stdout / stderr stream) for sync exec. Server should not apply default value for async exec, when omitted. The child process spawned by async execution should be killed when 1) server goes down 2) process exits by self 3) cancel operation is invoked type: integer default: 60000 maxBuffer: description: Largest amount of data (in bytes) allowed on stdout or stderr for sync exec. Server should not apply this limit to async execution. In sync exec, server may kill a child process that has exceeded limit. default value is 512KB, large enough. type: integer default: 524288 required: - command - args ExecutionResult: type: object description: execution response properties: error: description: error message when execution failed. type: string stdout: description: standard out of child process. type: string stderr: description: standard error of child process. type: string required: - stdout - stderr ChildProcess: type: object description: a process in execution, spawned by exec or other means. properties: pid: description: child process pid type: integer command: description: execution command in execution request type: string args: description: arguments of command in execution request type: array items: type: string execId: description: execution id from execution request type: string state: description: | State of process. Where CREATED - process is just created. no event has arrived yet. WORKING - some output on stdout/stderr is arrived. KILLING - sent kill signal, by cancel operation or some critical error event from the process. Invoking cancel operation to a process being killed should return error. EXITED - This process has exited already. Server is cleaning up the resources and not complete yet. Client should not expect that every exited process can be found with findProcs(). As KILLING state, cancellation will be rejected. type: string enum: - CREATED - WORKING - KILLING - EXITED foreground: description: if is true, this process is created from synchronous exec request. Som type: boolean startedAt: description: the time when this process is spawned type: string format: date-time exitCode: description: the exit code of child process. available with EXITED procs only. type: integer exitSignal: description: the signal named that killed this child process.(not always available) type: string required: - pid - command - args - execId - state - foreground - startedAt Alias: type: object description: alias to access file system using git or direct http(s) requests who can't call swagger api with proper tokens. Implemenations may provide some concrent url formats. Alias may be invalidated when the workspace it belongs is removed. Any removed alias will result 404 error or equivalent. properties: id: description: | id, and the path-fragment to access. Since this id is a path-fragment, any unsafe chars for file system path should not be included. Windows OS prohibits following characters. < (less than) > (greater than) : (colon) " (double quote) / (forward slash) \ (backslash) | (vertical bar or pipe) ? (question mark) * (asterisk) type: string workspaceId: description: id of the workspace that contains source of alias type: string sourcePath: description: the source of alias, relative path to workspace root directory. type: string required: - id - workspaceId - sourcePath