On 10/17/2011 01:18 PM, Ade Lee wrote:

...

Hi all,

I tried to put this on the dogtag wiki, but it did not seem to work. Will chat with Matt.

In the meantime, here is a copy for you guys to look at and comment on. It has most everything except the installation servlets and token operations (for which I need to think about the object model). If you look at the mapped servlets, you'll get a sense of what operations are covered in each URL mapping.

This is a first cut -- hopefully a good starting point for discussion. So please comment away!

Ade

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

Thanks Ade. Just a few questions after having a look.

1. I noticed we have the following key related resources:

PUT /pki/key "Add a key"

POST /pki/key "Modify a key"

In my quick readings, it appeared that the POST method was favored for creating brand new resources where PUT was used to modify existing ones? I think you have it backwards. PUT is the normal way for creating

On 10/17/2011 08:10 PM, Jack Magne wrote: things. The POST operation is very generic and no specific meaning can be attached to it. In general, use POST when only a subset of a resource needs to be modified and it cannot be accessed as its own resource; or when the equivalent of a method call must be exposed. http://developer.mindtouch.com/REST/REST_for_the_Rest_of_Us says this about POST: " usually either create a new one, or replace the existing one with this copy, where as POST is kinds of a catch all. " We could possibly use PUT for both add and modify if we wanted. I tend to favor making objects immutable, and to replacing whole objects when possible. However, I know that is not always possible, especially when working with a pre-existing API. So I'd say lets try to stick to PUT semantics where possible, but deliberately use POST when we are making finer grain API calls.

I also noticed that you have two GET versions of "pki/key". Is that kind of duplication encouraged? Or is that really just the same api entity with different input payloads?

2. You suggested I take a look at some of the TKS TokenServlet stuff. I noticed that we have a simple short list of servlets that appear to return very short lived resources. Examples being, session keys , encrypted data , and a block of randomly generated data.

I would imagine it would be a POST op like something as follows:

POST /pki/tks/sessionKey , which would return a link to the key itself? But does it make sense to have a "resource" for something so short lived, or does this concept even belong in such a design?

In general, REST works best if the service is stateless. Session based information should be minimized if possible.

3. I was just curious about the Java back-end for this design. Will we be using the JAX-RS stuff that provides annotations in the java code in order to hook all of this up?

I am not a fan of annotations. Under other circumstances, I might be prone to say "well, that is the way of the world" and go with JAX-RS, but since we don not yet have a set of Entity objects that would drive the JAX-RS, I am more prone to look at other alternatives. THere are good libraries for serializing to JSON or XML that should be sufficient for our needs, and that will keep us from having to make our API conform to JAX-RS. So my inclination is to say no to JAX-RS to start.

thanks, jack

Ade's document has founds its way into the wiki world: http://pki.fedoraproject.org/wiki/Dogtag_Future_Directions I might have made some Wiki errors in translation. If this contradicts Ade's spreadsheet, assume the spreadsheet is Canonical.

On 10/17/2011 05:35 PM, Adam Young wrote:

...

On 10/17/2011 01:18 PM, Ade Lee wrote:

...

Hi all,

I tried to put this on the dogtag wiki, but it did not seem to work. Will chat with Matt.

In the meantime, here is a copy for you guys to look at and comment on. It has most everything except the installation servlets and token operations (for which I need to think about the object model). If you look at the mapped servlets, you'll get a sense of what operations are covered in each URL mapping.

This is a first cut -- hopefully a good starting point for discussion. So please comment away!

Ade

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

Thanks Ade. Just a few questions after having a look.

1. I noticed we have the following key related resources:

PUT /pki/key "Add a key"

POST /pki/key "Modify a key"

In my quick readings, it appeared that the POST method was favored for creating brand new resources where PUT was used to modify existing ones? I think you have it backwards. PUT is the normal way for creating

On 10/17/2011 08:10 PM, Jack Magne wrote: things. The POST operation is very generic and no specific meaning can be attached to it. In general, use POST when only a subset of a resource needs to be modified and it cannot be accessed as its own resource; or when the equivalent of a method call must be exposed.

http://developer.mindtouch.com/REST/REST_for_the_Rest_of_Us says this about POST:

" usually either create a new one, or replace the existing one with this copy, where as POST is kinds of a catch all. "

We could possibly use PUT for both add and modify if we wanted.

My bad. I guess I chose to read a conflicting article on this subject: http://www.ibm.com/developerworks/webservices/library/ws-restful/ where it says the following: * To create a resource on the server, use POST. * To retrieve a resource, use GET. * To change the state of a resource or to update it, use PUT. * To remove or delete a resource, use DELETE. Perhaps I was further thrown off about the discussions I've seen about the idempotence property of PUT, whereby if you replay the same request more than once, you get the same result as the first time. Where in POST, if you repeat the exercise multiple times, you will get a list of new resources. Perhaps you could speak a little to that subject. I think I see now why he would chose PUT to create a key, because PUT replaces the entire resource, and POST can be used to replace part of a resource. If we were to modify a key or a request for a key, I'm guessing we would not replace the entity entirely.

I tend to favor making objects immutable, and to replacing whole objects when possible. However, I know that is not always possible, especially when working with a pre-existing API. So I'd say lets try to stick to PUT semantics where possible, but deliberately use POST when we are making finer grain API calls.

...

I also noticed that you have two GET versions of "pki/key". Is that kind of duplication encouraged? Or is that really just the same api entity with different input payloads?

2. You suggested I take a look at some of the TKS TokenServlet stuff. I noticed that we have a simple short list of servlets that appear to return very short lived resources. Examples being, session keys , encrypted data , and a block of randomly generated data.

I would imagine it would be a POST op like something as follows:

POST /pki/tks/sessionKey , which would return a link to the key itself? But does it make sense to have a "resource" for something so short lived, or does this concept even belong in such a design?

In general, REST works best if the service is stateless. Session based information should be minimized if possible.

Perhaps REST is not the way to go in the token space due to the nature of the beast.

...

3. I was just curious about the Java back-end for this design. Will we be using the JAX-RS stuff that provides annotations in the java code in order to hook all of this up?

I am not a fan of annotations. Under other circumstances, I might be prone to say "well, that is the way of the world" and go with JAX-RS, but since we don not yet have a set of Entity objects that would drive the JAX-RS, I am more prone to look at other alternatives. THere are good libraries for serializing to JSON or XML that should be sufficient for our needs, and that will keep us from having to make our API conform to JAX-RS. So my inclination is to say no to JAX-RS to start.

...

thanks, jack

Thanks for the clarifications!

Ade's document has founds its way into the wiki world:

http://pki.fedoraproject.org/wiki/Dogtag_Future_Directions

I might have made some Wiki errors in translation. If this contradicts Ade's spreadsheet, assume the spreadsheet is Canonical.

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

We all appear to be learning a lot about REST here :) I got a copy of "RESTful Web Services" by Sam Ruby et. al. and he explains it clearly. Turns out a lot of folks (including me) are confused about the roles of PUT and POST. PUT is used in general to either create a new resource or to replace an existing resource - but only if the client knows the intended URL of the resource. So, as was mentioned, this might be the case for users or for profiles where the URL of the resource /pki/profiles/userCert would be the URL for the userCert profile. POST is confusing because it has two usages. The first usage is the "create a subordinate URL" mode (POST-a). This is used when you are trying to create a new resource but the client does not know the URL of the resource. This is the case, for example, when we try to create a new certificate request. In this case, the client will do a POST to /pki/request - and the server will generate a request and return a link to /pki/request/<request_id>. The client can even do a POST-a to /pki/request/scep or /pki/request/enrollment or perhaps /pki/request/{profile_id} and have the server return a link to /pki/request/<request_id>. In this case, the link POST-ed to is not the parent link - but rather a "factory" link. POST has a second usage though, which is the "overloaded" mode (POST-b). This is when you POST to an existing URL so that it can change part of an existing resource (rather than replacing the whole thing which is a PUT operation). This is the kind of operation I had in mind for say, approving a certificate request or revoking a certificate. So, for example, to approve a certificate request, the client would POST-b to /pki/request/0xfeed and include say "operation=approve" in the POSTED parameters. The server would then process this request and could return the URL for the issued certificate. Or if a certificate is revoked, then the client would POST-b to /pki/certificate/0xbeef and include say "operation=revoke" in the POSTED parameters. The server would then process this request and set the status of the certificate to revoked, and return status to the client. POST-b is called overloaded because the real operation that is taking place is actually in the POST-ed parameters rather than the more limited operation of POST-a. In some sense, this is more RPC-like. It would be more "REST-ful" to replace the entire object using PUT - but this could be unacceptable in this context for a number of reasons. Once certificate requests and certs are in the CA they are stuck there under the control of the server and cannot be replaced by the client. And we need to cognizant of network traffic. If we did not want to use a POST-b type operation (and many people do in fact do use POST-b), there are a couple ways that we could proceed both of which involve adding new objects. Option A: We could decompose the certificate or request record into smaller objects. So for example, we could have the following for a cert request - Request (the CSR itself and submitted) and RequestStatus. Then, approving a request would be a PUT to /pki/requeststatus/0xfeed, replacing the object there. It will also have the side effect of generating a cert. There may be some merit to this approach, in that we often want to know the status of a request (which could the serial number of the certificate issued). And it separates the parts of the Request record that are immutable from those that can be changed by client interaction. Option B: We could use some pseudo-resources. Up to now, I have followed a principle of only creating resources that clients would want to link to. But you can create anything as a resource. One thing you could do is create a RequestApprover resource. Then, approving a request is would be doing a PUT to /pki/requestapprover passing a reference to the request. Ruby et. al. suggest this type of thing as a possible approach. It smacks as somewhat RPC-like, but it has the advantage of making explicit the operations being performed. Option C: Just do the POST-b. This is getting long -- I'll answer the other questions in a separate email. Ade On Mon, 2011-10-17 at 22:33 -0400, Adam Young wrote:

On 10/17/2011 10:00 PM, Jack Magne wrote:

...

On 10/17/2011 05:35 PM, Adam Young wrote:

...

...

On 10/17/2011 01:18 PM, Ade Lee wrote:

...

Hi all,

I tried to put this on the dogtag wiki, but it did not seem to work. Will chat with Matt.

In the meantime, here is a copy for you guys to look at and comment on. It has most everything except the installation servlets and token operations (for which I need to think about the object model). If you look at the mapped servlets, you'll get a sense of what operations are covered in each URL mapping.

This is a first cut -- hopefully a good starting point for discussion. So please comment away!

Ade

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

Thanks Ade. Just a few questions after having a look.

1. I noticed we have the following key related resources:

PUT /pki/key "Add a key"

POST /pki/key "Modify a key"

In my quick readings, it appeared that the POST method was favored for creating brand new resources where PUT was used to modify existing ones? I think you have it backwards. PUT is the normal way for creating

On 10/17/2011 08:10 PM, Jack Magne wrote: things. The POST operation is very generic and no specific meaning can be attached to it. In general, use POST when only a subset of a resource needs to be modified and it cannot be accessed as its own resource; or when the equivalent of a method call must be exposed.

http://developer.mindtouch.com/REST/REST_for_the_Rest_of_Us says this about POST:

" usually either create a new one, or replace the existing one with this copy, where as POST is kinds of a catch all. "

We could possibly use PUT for both add and modify if we wanted.

My bad. I guess I chose to read a conflicting article on this subject:

http://www.ibm.com/developerworks/webservices/library/ws-restful/

where it says the following: * To create a resource on the server, use POST. * To retrieve a resource, use GET. * To change the state of a resource or to update it, use PUT. * To remove or delete a resource, use DELETE. Perhaps I was further thrown off about the discussions I've seen about the idempotence property of PUT, whereby if you replay the same request more than once, you get the same result as the first time. Where in POST, if you repeat the exercise multiple times, you will get a list of new resources. Perhaps you could speak a little to that subject.

I think I see now why he would chose PUT to create a key, because PUT replaces the entire resource, and POST can be used to replace part of a resource. If we were to modify a key or a request for a key, I'm guessing we would not replace the entity entirely.

We are all learning this stuff, and I had a little too narrow a view before this discussion. One other resource I read states that you should use POST for anything that would not be idempotent: thus, PUT to create makes sense if you know the name to PUT it into, but you would use POST for creating a new identifier. So, I think that agrees with what you are saying.

So, yeah, I think you would PUT a key, assuming that the the PUT provides also the name of the key. You would POST a CSR to get a Certificate (in a simplified view) as the Certificate would get a Serial number, and that would be the unique ID.

I guess for creating a user, it would depend on if you were assigning the numeric UID whether it would be POST of a PUT.

I've a lot to learn about the Domain model here, so I'll let myself be guided by you guys as far as what the appropriate behavior of the business objects should be.

...

...

I tend to favor making objects immutable, and to replacing whole objects when possible. However, I know that is not always possible, especially when working with a pre-existing API. So I'd say lets try to stick to PUT semantics where possible, but deliberately use POST when we are making finer grain API calls.

...

I also noticed that you have two GET versions of "pki/key". Is that kind of duplication encouraged? Or is that really just the same api entity with different input payloads?

2. You suggested I take a look at some of the TKS TokenServlet stuff. I noticed that we have a simple short list of servlets that appear to return very short lived resources. Examples being, session keys , encrypted data , and a block of randomly generated data.

I would imagine it would be a POST op like something as follows:

POST /pki/tks/sessionKey , which would return a link to the key itself? But does it make sense to have a "resource" for something so short lived, or does this concept even belong in such a design?

In general, REST works best if the service is stateless. Session based information should be minimized if possible.

Perhaps REST is not the way to go in the token space due to the nature of the beast.

...

...

3. I was just curious about the Java back-end for this design. Will we be using the JAX-RS stuff that provides annotations in the java code in order to hook all of this up?

I am not a fan of annotations. Under other circumstances, I might be prone to say "well, that is the way of the world" and go with JAX-RS, but since we don not yet have a set of Entity objects that would drive the JAX-RS, I am more prone to look at other alternatives. THere are good libraries for serializing to JSON or XML that should be sufficient for our needs, and that will keep us from having to make our API conform to JAX-RS. So my inclination is to say no to JAX-RS to start.

...

thanks, jack

Thanks for the clarifications!

...

Ade's document has founds its way into the wiki world:

http://pki.fedoraproject.org/wiki/Dogtag_Future_Directions

I might have made some Wiki errors in translation. If this contradicts Ade's spreadsheet, assume the spreadsheet is Canonical.

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel

_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel