YaST/Research/YaaS/Team 2

From openSUSE

Conventions

Clear Namespaces

• /services namespace
• /services/ntp
• /service/ntp/config
• /service/ntp/config/servers

In this example, /services should return a document with possible links where to go. /services/ntp should return information about the service and also possible links.

In this case /services/ntp/config is a resource. It does not follow REST style 100% as there is only instance (we need research here on what is the convention) but it follows the rules: noun, no verbs in the url, and you can get it, set it, update it, or delete it (?). The GET method should also provide links to the different settings that could be interesting as resources.

The case of /service/ntp/config/servers is a REST resource.

Duncan 16:12, 1 July 2008 (UTC) discussion pending on what to do with actions. REST does not allow actions to be in the URLs, but we need them for things like service start/stop

Data Exchange

We will use object classes to model resources (data used by YaST) and serialize instances of these classes to various formats (XML and JSON will be a good start) to exchange them between the UI (client) and API (listener) servers.

XML Structure

Both Ruby (Rails) and Python (Django) support both XML and JSON serialization, generic or Model/ActiveRecord, but both use a different structure. The code will need to be adapted or we will need to write our own serializers. We agreed on the following structure:

<resource-name-plural type="array">
  <resource-name>
    <attr1-name></attr1-name>   <!-- type="string" by default -->
    <attr2-name type="int"></attr2-name>
    <attr3-name type="bool"></attr3-name>
  </resource-name>
  <resource-name>
    ...
  </resource-name>
</resource-name-plural>

<singleton-resource>
...
</singleton-resource>

We should add the details (create XML schema) when implementing the serializers.

For example:

<network-devices type="array">
  <network-device>
    <name>eth0</name>
    <mac>ff-ff-ff-ff-ff</mac>
    <active type="bool">true</active>
  </network-device>
  <network-device>
    <name>eth1</name>
    <mac>ee-ee-ee-ee-ee</mac>
    <active type="bool">false</active>
  </network-device>
</devices>

Another example is the systemtime below.

For collection resources like "things" they should be in a url /things, while singleton resources can stay in /mything.

For collection resources, they should provide a /things/id accessor. Not applicable for singleton resources.

MIME Type

API server will determine the MIME type of the data sent or requested in the following two ways:

• CONTENT_TYPE META tag of the request header
• resource name extension (e.g. /users.xml or /users.json)

The API server will process the received data according to this MIME type and/or generate a response with requested MIME type.

API Possibilities

Time

GET /system/systemtime

returns

<systemtime>
  <time>07 409362008
  </time>
  <timezone>CEST
  </timezone>
  <isUTC type="boolean">false</isUTC>
</systemtime>

PUT /system/systemtime

GET /system/systemtime/time

returns time

GET /system/systemtime/timezone

Checking permissions

GET /acl/time

Packages

It is more complex :-)

GET /packages

returns package1(attr1,attr2,..), package2(attr1,attrr2,..)

GET /packages/pakckage1

returns attr1,atrr2,.... of a package

GET /repositories/repo1

returns name,Url, Link to additional data "full" which would be

GET /repositories/repo1/full

Users

GET /users?view=ids

returns user1,user2,user3

GET /users/root

returns homedir,.....

PUT /users/root PUT /users/root/password

some use:

GET /acl/users/root/password

returns true/false

Another possibility for restricting result values:

GET /users?limit=100

returns user1..user100

GET /users?start=101&limit=100

returns user101..user200

GET /users?regexp=a*

returns a1,a2,a3

NTP

GET /services/ntp/ == status

PUT /services/ntp/ == reload

DELETE /services/ntp/ == stop

POST /services/ntp/ == start

GET /services/ntp/config

returns config of server1,server2,server3,...

GET /services/ntp/config/servers

returns server1, server2, server3

PUT /services/ntp/config/servers

POST /service/ntp/config/servers

Create a new server

DELETE /service/ntp/config/servers/server1

/etc/sysconfig

GET /sysconfig

returns links to apache,network,firewall

GET /sysconfig/apache GET /sysconfig/apache/modules PUT /sysconfig/apache/modules

Apache

GET /services/apache/rhosts

returns links to myserver, otherserver

GET /services/apache/rhosts/myserver

POST /services/apache/rhosts POST /apache/sysconfig

Code

• git clone git://git.opensuse.org/projects/yast/rest-service.git
• git clone git://git.opensuse.org/projects/yast/web-client.git

TODO

• agree on JSON structure (maybe there is a unique equivalent for the above XML?)