HTTP API specification

Mobyle2 HTTP API

Disclaimer: this document is a design document. It is a work in progress, open to suggestions and corrections.

This document is aimed at describing the different HTTP methods which should be made available by a mobyle2 server.

List the different mobyle2 servers

Request:

GET HTTP://[mobyle2 URL]/servers/

Response:

{"server1":{"url":"[mobyle2 server 1 URL]",
            "services":["service_1","service_2","service_3"],
            "active":true},
 "server2":{"url":"[mobyle2 server 2 URL]",
            "services":["service_2","service_4","service_6"],"active":true}
}

Notes:

• the current method of mobyle (net_servers_list.py) publishes support emails. I do not know if we should reproduce this, as it may be a source of spam.
• current method sends back the URL of the repository. Since we will be using a consistent HTTP API, it should not be necessary to provide this as a workaround to configuration variability.

Get the information about a particular server

Same as above, but specifies a server name as a key in the path

Request:

GET HTTP://[mobyle2 URL]/servers/server1/

Response:

{"url":"[mobyle2 server 1 URL]",
       "services":["service_1","service_2","service_3"],
       "active":true}

List the different mobyle2 services

Request:

GET HTTP://[mobyle2 URL]/services/

Response:

{ "service1::project1::server1": {"name":"service1",
                                  "server":"server_1",
                                  "project":"project",
                                  "type":"program",
                                  "exported":true,
                                  "disabled":false,
                                  "authorized":true},
  "service2::project1::server1": {"name":"service2",
                                  "server":"server_1",
                                  "project":"project",
                                  "type":"program",
                                  "exported":true,
                                  "disabled":false,
                                  "authorized":true}
}

Here:

• "project" is the name of the project to which the service belongs, it can be a user-level project or a server-level service. If the service is server-level, "project" key should not be mentionned or specify a reserved word,
• "type" is the type of the service, "program", "workflow" or "widget",
• "exported" (boolean) specifies if the service can be called from another server,
• "disabled" (boolean) specifies if the service has been disabled by the mobyle server administrators, e.g. for maintenance purposes,
• "authorized" (boolean) specifies if the service can be called by the current user (the one performing the HTTP request).

Get the information about a particular service

Same as above, but specifies a service "full name" (service name+project name+server name) as a key in the path.

Request:

GET HTTP://[mobyle2 URL]/services/service1::project1::server1

Response: {"name":"service1", "server":"server_1", "project":"project", "type":"program", "exported":true, "disabled":false, "authorized":true}

List mobyle2 users

Lists the users of the server. This should be accessible only to administrators.

Request:

GET HTTP://[mobyle2 URL]/users/

Response:

{"00000000001": {"email":"herve@example@com",
                 "type":"authenticated",
                 "authentication_type":"ldap",
                 "status":"active",
                 "is_admin":true,
                 "groups":["group1","group2"],
                 "projects": ["00000000001","00000000002","00000000003"]},
 "00000000002": {"email":"[email protected]",
                 "type":"anonymous",
                 "status":"active",
                 "is_admin":false,
           	     "groups":[],
                 "projects": ["00000000004"]
                },
 "00000000003": {"type":"anonymous",
                 "status":"suspended",
                 "status_message":"you have been suspended because you abuse our resources. please contact us if you wish your account to be reactivated",
                 "is_admin":false,
                 "groups":[],
                 "projects": ["00000000005"]
                 },
 "00000000004": {"type":"anonymous",
                 "status":"pending",
                 "is_admin":false,
                 "groups":[],
                 "projects": ["00000000006"]
                }
}

Get the information for a particular user

Same as above, but specifies a user ID. Restricted to the user itself or an administrator.

Request:

GET HTTP://[mobyle2 URL]/users/00000000004

Response:

{"type":"anonymous", "status":"pending", "is_admin":false, "groups":[], "projects": ["00000000006"] }

List projects

Lists the users of the server. This should be accessible only to administrators.

Request:

GET HTTP://[mobyle2 URL]/projects

Response:

{"00000000001": 
    {"owner":"00000000001",
     "managers":["00000000010","00000000012","00000000015"],
     "contributors":["00000000011"],
     "watchers":[],
     "services":["workflow_1","workflow_2","workflow3"],
     "jobs":["00000000001","00000000002","00000000003"],
     "data":["00000000001","00000000002"],
     "favorites":["server1/p"]
    },
 "00000000002":
    {"owner":"00000000001",
     "managers":[],
     "contributors":["00000000012"],
     "watchers":[],
     "services":[],
     "jobs":[],
     "data":[]
    }
}

Get the information for a particular project

Same as above, but specifies a project ID. Restricted to members of the project or an administrator.

Request: GET HTTP://[mobyle2 URL]/projects/00000000001

Response:

{"owner":"00000000001",
 "managers":["00000000010","00000000012","00000000015"],
 "contributors":["00000000011"],
 "watchers":[],
 "services":[],
 "jobs":[],
 "data":[]
}