File System

GET /resources/files/{workspace}/{application}/{path} - get file or directory under workspace

- The ?metadata param can be used to retrieve a JSON representation a file/dir without getting all its contents. The JSON has name, path, modified, and hasChildren fields.

- The ?recurse param can be used to retrieve a whole subtree of metadata.

- The ?flat param can be used to retrieve a whole subtree of metadata as a list (with no children specified for directories).

- The ?virtual param can be used in conjunction with the ?metadata param to retrieve a directory listing that contains files from equivalent directories in the application's dependencies. For example, a search for /my-app/config?metadata&virtual would return all of the files under /config in the app and its dependencies (zero.core, zero.network, etc.).

- The ?extensions param can be used in conjunction with the ?metadata param to retrieve metadata entries on a subset of a directory tree. Requests such as /resources/files/some/dir?extensions=html,css would return only .html and .css files in the directory; if the ?recurse param is used, the request matches files in a whole sub-tree.

PUT /resources/files/{workspace}/{application}/{path} - create or modify the contents of a file. PUT request body should contain the new file content. If this is a create, the request should have the HTTP header If-None-Match = *.

DELETE /resources/files/{workspace}/{application}/{path} - deletes a file or directory tree.

Examples of ?metadata requests:

GET /resources/files/my-workspace/my-app/config?metadata

Returns:

{
        name: "config", 
        path: "/resources/files/my-workspace/my-app/config", 
        modified: 1234567890, 
        directory: true, 
        children: ["zero.config", "ivy.xml"], 
        virtual: false
}

GET /resources/files/my-workspace/my-app/config?metadata&recurse

Returns:

{
        name: "config", 
        path: "/resources/files/my-workspace/my-app/config", 
        modified: 1234567890, 
        directory: true, 
        virtual: false,
        children: [
                {
                        name: "zero.config", 
                        path: "/resources/files/my-workspace/my-app/config/zero.config", 
                        modified: 1234567890, 
                        directory: false, 
                        virtual: false,
                        children: null
                },
                {
                        name: "ivy.xml", 
                        path: "/resources/files/my-workspace/my-app/config/ivy.xml", 
                        modified: 1234567890, 
                        directory: false, 
                        virtual: false,
                        children: null
                }
        ]
}

GET /resources/files/my-workspace/my-app/config?metadata&recurse&virtual

Returns:

{
        name: "config", 
        path: "/resources/files/my-workspace/my-app/config", 
        modified: 1234567890, 
        directory: true, 
        virtual: false,
        children: [
                {
                        name: "zero.config", 
                        path: "/resources/files/my-workspace/my-app/config/zero.config", 
                        modified: 1234567890, 
                        directory: false, 
                        virtual: false,
                        children: null
                },
                {
                        name: "ivy.xml", 
                        path: "/resources/files/my-workspace/my-app/config/ivy.xml", 
                        modified: 1234567890, 
                        directory: false, 
                        virtual: false,
                        children: null
                },
                {
                        name: "security", 
                        path: "/resources/files/my-workspace/my-app/config/security", 
                        modified: 1234567890, 
                        directory: true, 
                        virtual: true,
                        children: [
                                {
                                    name: "forms.config", 
                                    path: "/resources/files/my-workspace/my-app/config/security/forms.config", 
                                    modified: 1234567890, 
                                    directory: false, 
                                    virtual: true,
                                    children: null
                                }
                        ]
                },
        ]
}

GET /resources/files/my-workspace/my-app/config/zero.config?metadata

Returns:

{
        name: "zero.config", 
        path: "/resources/files/my-workspace/my-app/config/zero.config", 
        modified: 1234567890, 
        directory: false, 
        children: null, 
        virtual: false
}

Note that ?recurse and ?virtual only apply to directories.

Workspaces

POST /resources/workspaces - create new workspace with JSON representation. The JSON should have a single field: name.

- Returns Location header that points to /files/{workspace}

Applications

POST /resources/workspaces/{id}/applications/{id} - create a new application with JSON representation; this will invoke the zero.tools commands needed to create the app from the template. The JSON should have a single field: name.

- Returns Location header that points to /files/{workspace}/{application}

Processes

GET /resources/workspaces/{id}/applications/{id}/process - JSON representation of running app (process)

POST /resources/workspaces/{id}/applications/{id}/process - start an app as a new process

The body of the POST request should be a JSON object that has a property named "debug" with a value of true or false (boolean values, not strings). This provides an indication of whether to launch the process in debug mode or not.

DELETE /resources/workspaces/{id}/applications/{id}/process - stop an app/process

Custom Actions

POST /resources/ide - with a JSON object that has a "name" and "params" fields. This can be used to invoke methods that are implemented on the server side in /app/scripts/CustomActions.groovy.

Repository

The word repository has a couple different meanings for us. There is a local repository that serves as the input for dependency resolution. Then there is a remote repository chain that is used to populate the local repository, either manually or during dependency resolution. While both repository types operate on the same basic unit (the component), operations on them are different enough that they are treated as two separate resource types.

Noun	Verb	Payload	Response	Description
/components	GET		JSON array of compact component	list the local repository
/components	POST	component		download a component from the remote chain to the local repository
/components/{componentId}	DELETE			remove component from the local repository
/libraryComponents	GET		JSON array of compact component	list the remote repository chain; two query parameters are available: org and module

Data type	Description
component	JSON-encoded string: { name: String, org: String, rev: String }
compact component	JSON-encoded string: { name: String, org: String, rev: Array of String }
componentId	String with the format "org:name:rev"

Dependencies

Need to model two types of dependencies: dependencies (explicit dependencies, which are specified in the ivy.xml file) and resolvedDependencies.

dependencies

URI	Method	Representation	Description
/resources/applications/{appid}/dependencies	GET	JSON (deplist)	List of dependencies
	POST	JSON (deplist)	Set the dependencies; invoke "resolve"

This resource is persisted in the dependencies stanza of the ivy.xml file. For example:

    <dependencies>
        <dependency name="zero.core" org="zero" rev="1.0+"/>
        <dependency name="zero.data" org="zero" rev="1.0+"/>
    </dependencies>

GET /resources/applications/{aid}/dependencies

Returns:

[
  {"name" : "zero.core", "org" : "zero", "rev" : "1.0+"},
  {"name" : "zero.data", "org" : "zero", "rev" : "1.0+"}
]

POST /resources/applications/{aid}/dependencies

Send entity:

[
  {"name" : "zero.core", "org" : "zero", "rev" : "1.0+"},
  {"name" : "zero.other", "org" : "zero", "rev" : "1.0+"}
]

Server actions should include:

• update ivy.xml
• invoke resolve
• report what needs to be pulled from external repository
• user approves external resolve
• perform external resolve
• update .zeroresolved.properties

• report errors

For now:

• update ivy.xml
• invoke resolve (drive external, if needed)
• update .zeroresolved.properties

• no errors

return 200

---

Regarding the "tell if a process is running by GETing it and watching for 404" - I think this is ok as long as the 404 returns quickly.

-- brettk - 25 Jan 2008

I implemented this for a dW article by checking for the existence of $apphome/zero.pid - that's pretty quick.

-- danjemiolo - 25 Jan 2008

For the app create, I think I'm going to need to pass in just an app name and a port number. I spoke with Steve; I don't think we're going to do the dynamic port allocation like Zero alive has.

-- brettk - 25 Jan 2008

We'll just specify application name. Every new application will get the default config. The developer can manage as needed. -- Steve

ppDan, the zero.ide.services is working well so far, but I quickly realized that in addition to the current options of ?metadata&recurse I think I need another one which would only return files (no directories) and in one array, not grouped under directories. I need this to build the flat list of files. Does that make sense?

-- edchat - 29 Jan 2008

I think we should have an option of including hidden files and directories or not. things like .svn directories , .project files etc should not be shown in the ui, unless the user asks for them, and we don't want to send all of that data over the wire unless we need to show it...

-- edchat - 31 Jan 2008