[yast-devel] Registration Rest Api
Hi hackers, I want to share my current thoughts about the Rest Api for the registration. Please have a look and feel free to comment and ask. Registration Configuration: --------------------------------- * /registration/config GET get registration server returns: <registrationconfig> <server> <url>https://myregistration.server.com/center/regsvc</url> </server> </registrationconfig> PUT set new registration server the certificate is inclueded as well post data: <registrationconfig> <server> <url>https://somewhere.else.com/center/regsvc</url> </server> <certificate> <data> <![CDATA[ -----BEGIN CERTIFICATE----- MIIFIDCCBAigAwIBAgIJAPP6cY6saTFlMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYD VQQGEwJERTEPMA0 ......... 60QTef32lxeuVH9Kve8gGZiMwDqcJfl J8NLO3kNW3Zys2p4agg22yttmUs= -----END CERTIFICATE----- ]]> </data> </certificate> </registrationconfig> return value is the same as for GET Run Registration: --------------------------------- * /registration POST run registration and return the/a result post data: <registration> <options> <debug>2</debug> <nooptional>1</nooptional> <nohwdata>1</nohwdata> <forcereg>0</forcereg> <httpproxy>http://my.proxy</httpproxy> <httpsproxy>http://my.proxy</httpsproxy> </options> <arguments> <argument> <name>key</name> <value>val</value> </argument> ... </arguments> <registration> returns: <registration> <status>finished|missinginfo|error</status> <message>Some text to display</message> <guid>systemsguid</guid> <!-- in case of missing arguments --> <missingarguments> <argument> <name>missingkey</name> <type>string|text|number</type> </argument> ... </missingarguments> <!-- in case of success and services or repos got changed --> <changedrepos> <repo> <name>repoName</name> <alias>myRepoName</alias> <urls> <url>http://some.host/repo/xy</url> ... </urls> <priority>80</priority> <autorefresh>true</autorefresh> <enabled>true</enabled> <status>added|deleted</status> </repo> ... </changedrepos> <changedservices> <service> <name>some-serv1</name> <url>http://some.host/services/serv1</url> <status>added|deleted</status> </service> ... </changedservices> </registration> There is only one action to perform the registration. And all data has to be send for each request, as it operates in stateless context. The following action depends on the answer to the request. If there are arguments missing a following call is needed (together with the additional arguments). Otherwise the changes to the package system are returned if the registration succeeded. Thanks for comments. Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
J. Daniel Schmidt napsal(a):
Hi hackers,
I want to share my current thoughts about the Rest Api for the registration. Please have a look and feel free to comment and ask.
Registration Configuration: --------------------------------- * /registration/config GET get registration server
returns:
<registrationconfig> <server> <url>https://myregistration.server.com/center/regsvc</url> </server> </registrationconfig>
Hi, just few notes. Why get doesn't get certificate? Maybe someone find usefull to check server certificate
PUT set new registration server the certificate is inclueded as well
post data:
<registrationconfig> <server> <url>https://somewhere.else.com/center/regsvc</url> </server> <certificate> <data> <![CDATA[ -----BEGIN CERTIFICATE----- MIIFIDCCBAigAwIBAgIJAPP6cY6saTFlMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYD VQQGEwJERTEPMA0 ......... 60QTef32lxeuVH9Kve8gGZiMwDqcJfl J8NLO3kNW3Zys2p4agg22yttmUs= -----END CERTIFICATE----- ]]> </data> </certificate> </registrationconfig>
return value is the same as for GET
Run Registration: ---------------------------------
* /registration
I am not sure if you don't have problems run registration as controller and have registration/config for configuration. Maybe you should use another subdirectory for registration?
POST run registration and return the/a result
post data:
<registration> <options> <debug>2</debug> <nooptional>1</nooptional> <nohwdata>1</nohwdata> <forcereg>0</forcereg> <httpproxy>http://my.proxy</httpproxy> <httpsproxy>http://my.proxy</httpsproxy> </options>
<arguments> <argument> <name>key</name> <value>val</value> </argument> ... </arguments> <registration>
returns:
<registration> <status>finished|missinginfo|error</status> <message>Some text to display</message> <guid>systemsguid</guid>
<!-- in case of missing arguments -->
I think that missing argument should be reported as error, also another controller handle it as error (I plan add specific exception for arguments missing/invalid). Do you have any reason to respond it as success response? Also status error is not good I think...thats reason why status code exist, just report problem in status code and explain problem in response. Don't mix success registration and problematic. Josef -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Friday 18 September 2009 01:50:57 josef reidinger wrote:
Registration Configuration: --------------------------------- * /registration/config GET get registration server
returns:
<registrationconfig> <server> <url>https://myregistration.server.com/center/regsvc</url> </server> </registrationconfig>
Hi, just few notes. Why get doesn't get certificate? Maybe someone find usefull to check server certificate
The idea is, to do all the certificate checking (and downloading the cert from a url) in the web-client and then the web-client PUTs the certificate itself to the target system. PUTting the certificate to the server only imports it to the certificates in /etc/ssl/certs. Ok, I could check for a fixed file name and dump it again - sure.
<!-- in case of missing arguments -->
I think that missing argument should be reported as error, also another controller handle it as error (I plan add specific exception for arguments missing/invalid). Do you have any reason to respond it as success response? Also status error is not good I think...thats reason why status code exist, just report problem in status code and explain problem in response. Don't mix success registration and problematic.
The design of the registration process is different to any other module that does configuration stuff. 1. A system does not know if it is registered or not You need to do a registration to find out. But after you registered you can not be sure, tthat the system is still registered - only the registration server knows, and by design you can not query for that status. 2. A system does not know what arguments (values) to ask from the user; it does not know if there might be something missing in the first place; you need to do a registration to find out, what arguments are needed for a registration. Thus the status "missing info" is a valid status within the workflow and not an error. Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
* J. Daniel Schmidt <jdsn@suse.de> [Sep 17. 2009 22:14]:
Run Registration: ---------------------------------
* /registration
As Josef already mentioned, you might want to rename this to /registration/register. This way the url names the action ('register') and also matches Rails controller/action pattern for urls.
POST run registration and return the/a result
post data:
<registration> <options> <debug>2</debug> <nooptional>1</nooptional> <nohwdata>1</nohwdata>
This negation seems awkward. What's wrong with <optional> and <hwdata> ? Boolean attributes should also get boolean values (i.e. 'true' instead of '1'). But such details (type of attributes) are better left to ActiveResource.
<forcereg>0</forcereg> <httpproxy>http://my.proxy</httpproxy> <httpsproxy>http://my.proxy</httpsproxy>
Hmm, the proxy should belong to the network settings.
</options>
<arguments> <argument> <name>key</name> <value>val</value> </argument>
This also looks awkward (should be <key>value</key>) but thats probably due to ActiveResource.
... </arguments> <registration>
returns:
<registration> <status>finished|missinginfo|error</status> <message>Some text to display</message>
Where does this message come from, how is it translated ? Language setting should be a property of the frontend (webclient), the service has no idea about the UI language. For the error results, use different class definitions all derived from a common 'error' class. I guess discussing these classes is easier than looking at raw xml.
There is only one action to perform the registration. And all data has to be send for each request, as it operates in stateless context. The following action depends on the answer to the request. If there are arguments missing a following call is needed (together with the additional arguments).
Is there a state diagram available showing how requests and answers relate ? Klaus --- SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Friday 18 September 2009 11:23:17 Klaus Kaempf wrote:
* J. Daniel Schmidt <jdsn@suse.de> [Sep 17. 2009 22:14]:
Run Registration: ---------------------------------
* /registration
As Josef already mentioned, you might want to rename this to /registration/register. This way the url names the action ('register') and also matches Rails controller/action pattern for urls.
Well Daniel is correct that a REST API should be a name and not a verb, because a POST should "create a registration" and not "register", so the right thing would be to post to /somenamespace/registrations. Or? Duncan -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
Duncan Mac-Vicar P. wrote:
On Friday 18 September 2009 11:23:17 Klaus Kaempf wrote:
* J. Daniel Schmidt <jdsn@suse.de> [Sep 17. 2009 22:14]:
Run Registration: ---------------------------------
* /registration As Josef already mentioned, you might want to rename this to /registration/register. This way the url names the action ('register') and also matches Rails controller/action pattern for urls.
Well Daniel is correct that a REST API should be a name and not a verb, because a POST should "create a registration" and not "register", so the right thing would be to post to /somenamespace/registrations.
Or?
Duncan
I think we should have registration/config for configuration and registration/status for registry (update of status from non-registered to registered is intuitive for me and it also can return current status if user is registered or not). -- Josef Reidinger YaST team maintainer of perl-Bootloader, YaST2-Repair, webyast modules language and time -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Monday 21 September 2009 09:24:33 Josef Reidinger wrote:
I think we should have registration/config for configuration and registration/status for registry (update of status from non-registered to registered is intuitive for me and it also can return current status if user is registered or not).
This is not possible. A client does not know if it is registered or not. You need to ask the registration server. The target system can ask the registration server but this means to run the registration again (which might include further interaction - you never know). Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Monday 21 September 2009 00:03:28 Duncan Mac-Vicar P. wrote:
Run Registration: ---------------------------------
* /registration
As Josef already mentioned, you might want to rename this to /registration/register. This way the url names the action ('register') and also matches Rails controller/action pattern for urls.
Well Daniel is correct that a REST API should be a name and not a verb, because a POST should "create a registration" and not "register", so the right thing would be to post to /somenamespace/registrations.
Or?
In this case I'd say /registration/registration is the right path. Honestly. But - a registration is not created, thats where the model differs from the real world. A registration gets run. But it only exists on NCC - until somebody changes it there. The target system will never know about that. Nor can it say that it 'is' registered. It can only repeat its registration run. Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Friday 18 September 2009 11:23:17 Klaus Kaempf wrote:
* /registration
As Josef already mentioned, you might want to rename this to /registration/register. This way the url names the action ('register') and also matches Rails controller/action pattern for urls.
Yes, it should be compatible with all other URLs. I discussed it with Schubi last week, and we decided to keep the URL short, as this action is the only one available. But I'm fine with renaming it to /registration/register
POST run registration and return the/a result
post data:
<registration> <options> <debug>2</debug> <nooptional>1</nooptional> <nohwdata>1</nohwdata>
This negation seems awkward. What's wrong with <optional> and <hwdata> ? Boolean attributes should also get boolean values (i.e. 'true' instead of '1').
Sure, only debug mode is non-boolean. Will change it.
But such details (type of attributes) are better left to ActiveResource.
<forcereg>0</forcereg>
This one is boolean, not part of the proxy and a needed switch.
<httpproxy>http://my.proxy</httpproxy> <httpsproxy>http://my.proxy</httpsproxy>
Hmm, the proxy should belong to the network settings.
Yes this is correct, but for some reason we configured it manually in the current registration. I'll find out about if we really need this option.
</options>
<arguments> <argument> <name>key</name> <value>val</value> </argument>
This also looks awkward (should be <key>value</key>) but thats probably due to ActiveResource.
No, its because the name of the keys are dynamic. There is no fixed list of possible keys. There can be any of them.
... </arguments> <registration>
returns:
<registration> <status>finished|missinginfo|error</status> <message>Some text to display</message>
Where does this message come from, how is it translated ?
The registration server can send translated messages if the language is supported by NCC (see as well "suse_register --locale=XY").
Language setting should be a property of the frontend (webclient), the service has no idea about the UI language.
The target system has a default language. Thats the language the system gets registered with. And if a translation exists for this language the registration server sends answers in this language - these could be displayed. But if we want to keep the web-client's language setting separate from one on the target system then we need to have static texts and use exit codes to identify the actual status.
For the error results, use different class definitions all derived from a common 'error' class. I guess discussing these classes is easier than looking at raw xml.
Missing information is not an error, but a valid status within the registration workflow - see my answer to Josef's eMail.
There is only one action to perform the registration. And all data has to be send for each request, as it operates in stateless context. The following action depends on the answer to the request. If there are arguments missing a following call is needed (together with the additional arguments).
Is there a state diagram available showing how requests and answers relate ?
I'll create one. Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Monday 21 September 2009 17:17:27 J. Daniel Schmidt wrote:
Is there a state diagram available showing how requests and answers relate ?
I'll create one.
Here are two diagrams showing how the registration is supposed to work: http://en.opensuse.org/YaST/Web/Development/Registration Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
J. Daniel Schmidt napsal(a):
On Monday 21 September 2009 17:17:27 J. Daniel Schmidt wrote:
Is there a state diagram available showing how requests and answers relate ? I'll create one.
Here are two diagrams showing how the registration is supposed to work: http://en.opensuse.org/YaST/Web/Development/Registration
Ciao, Daniel
Hi, Does information needed for registration need more steps or is sufficient to ask backend for needed arguments and then show it? If this is second case then you can send get to backend which return what parameters they need and then show this parameters and doesn't return (dynamic create content one time is possible, but longer session between user, frontend and backend is quite hard to do with stateless REST API). So I think that workflow for registration should be ask backend what information is needed -> generate form based on required arguments (rails have some support for this task) -> register if some error occure, then use error report and go from beginning (or let values in form it is not important). Josef -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Friday 18 September 2009 11:23:17 Klaus Kaempf wrote:
* J. Daniel Schmidt <jdsn@suse.de> [Sep 17. 2009 22:14]:
Run Registration: ---------------------------------
* /registration POST run registration and return the/a result post data:
<registration> <options> <debug>2</debug> <nooptional>1</nooptional> <nohwdata>1</nohwdata>
This negation seems awkward. What's wrong with <optional> and <hwdata> ? Boolean attributes should also get boolean values (i.e. 'true' instead of '1').
When I wanted to update the docu to the wiki I reread your comment. I agree that this negation looks awkward. This negation is not my invention. It is part of the registration. To send optional and hardware data is the default. It can be disabled using the negated switches. When they are called "optional" and "hwdata" here one might expect that omitting them might mean to not send the data - which is a wrong assumption. Ciao, Daniel -- J. Daniel Schmidt <jdsn@suse.de> SUSE Linux Products GmbH Research & Development Maxfeldstr. 5 GF: Markus Rex, HRB 16746 (AG Nürnberg) D-90409 Nürnberg -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
participants (5)
-
Duncan Mac-Vicar P. -
J. Daniel Schmidt -
Josef Reidinger -
josef reidinger
-
Klaus Kaempf