Hi Nirmal,
camel case should not be used because:
- the domain name (aka host) is not case sensitive by definition,
- some servers treat the path not as case sensitive
thus, camel case style will be confusing, implying differences in API names
that don't exist. Nevertheless, a couple of vendors use camel style, but
the public critique is that these APIs are designed by Java programmers ;-)
Using underscores is typically seen as problematic, because API URLs are
often rendered in HTML pages (e.g. in documentation; as error descriptions;
in generated pages;...). And the browser will interpret them as links,
thus, rendering them as underlined: the underscore is then hard to read.
As a *consequence*, the general recommendation is to *use hyphens* ("-").
:-)
Best regards,
Frank
2015-04-01 10:34 GMT+02:00 Nirmal Fernando <nir...@wso2.com>:
> This is very helpful Frank, and as you mentioned these
> controlled-resources are always lead to discussion. Do you have any
> comments on the usage of '-' instead of camel case ?
>
> On Tue, Mar 31, 2015 at 10:51 PM, Frank Leymann <fr...@wso2.com> wrote:
>
>> Hi Jo, hi Manu,
>>
>> how to cope with "actions" that cannot be mapped onto the CRUD methods on
>> individual resources or collection resources is always a matter of
>> discussion and taste when designing REST interfaces.
>>
>> A very often used guideline is to use so-called *controller resources*.
>> I controller resources represents an application specific operation that
>> acts on one or more individual resources or collection resources in an
>> atomic manner. The copy-api is such a controller resource.
>>
>> There are two ways to design URIs of controller resources. First, you
>> append the name of the "action" to one of the URIs that you atomically want
>> to act on, and other parameters follow in the query string; sometimes it is
>> random which of the URIs to append the name of the action to - this is why
>> I personally don't like this naming scheme. The second design uses the name
>> of the "action" as URI and the query string contains the parameters
>> required by the "action" - this is what I personally prefer because it's
>> deterministic and symmetric (but again, it's a matter of taste. However
>> you design the URI you use POST as the http method to interact with the
>> controller resource.
>>
>> In our concrete case of copy-api the two options are:
>>
>> 1. /apis/{apiId}/copy-api
>> or
>> 2. /copy-api?{apiID}
>>
>> By the way, the similar case is the change-lifecycle controller resource.
>>
>> Another reason why I like API design (2) is as follows. Often you need
>> actions on individual resources that don't manipulate (or retrieve) a
>> resource. Such actions are designed as resources called *processing
>> function resources* or *computing resources*. The standard example is
>> verifying a credit card. The design of the URIs of such processing function
>> resources always follows number (2). Because processing functions
>> resources never manipulate resources its http method is always GET, by the
>> way.
>>
>> Finally, controller resources are used from time to time to update parts
>> of individual resources. Http has the PATCH method for this purpose, but
>> not all web servers support PATCH. PUT itself will substitute complete
>> resources, i.e. updating parts of an individual resource is not intended
>> via PUT. This is why specific controller resources may be used for partial
>> updates.
>>
>>
>>
>>
>> Best regards,
>> Frank
>>
>> 2015-03-30 19:57 GMT+02:00 Joseph Fonseka <jos...@wso2.com>:
>>
>>> Hi Manu
>>>
>>> Copy API will duplicate not just the resource it will duplicate all the
>>> resources associated to it as well eg. Documents. So re-posting the API
>>> resource json will not be sufficient in this particular case. But there is
>>> a possibility of duplicating the associated resources from the client as
>>> well but IMHO that will complicated the client implementation.
>>>
>>> Nevertheless its a problem that we face how to represent an action as a
>>> resource. Currently we have adopted "<action>-<resource or attr acted
>>> upon>" kind of notation.
>>>
>>> Regards
>>> Jo
>>>
>>>
>>> On Mon, Mar 30, 2015 at 4:49 PM, Manuranga Perera <m...@wso2.com> wrote:
>>>
>>>> Hi Frank,
>>>> I see few endpoints representing actions rather than resources. For
>>>> example POST /apis/{apiId}/copy-api.
>>>> This is an action because there is no resource called copy-api. I
>>>> would rather see it as posting an existing API to the /apis.
>>>> In a HATEOS system we will be posting the href of an existing API to
>>>> /apis endpoint. Since we are not there yet, we can use some json
>>>> representation of the existing API.
>>>>
>>>> What do you think?
>>>>
>>>> On Tue, Mar 31, 2015 at 12:03 AM, Joseph Fonseka <jos...@wso2.com>
>>>> wrote:
>>>>
>>>>> Hi Frank
>>>>>
>>>>> Thanks for the feedback. And it is nice to see how we can control
>>>>> cashing and concurrency with the additional headers. We will update the
>>>>> remaining APIs with the same concepts.
>>>>>
>>>>> Please let us know a convenient time for a call to discuss on it
>>>>> further.
>>>>>
>>>>> Also we will try to document these design decisions and concepts to
>>>>> benefit APIs created in the future.
>>>>>
>>>>> BTW. The changes were pushed to the repo.
>>>>>
>>>>> Thanks
>>>>> Jo
>>>>>
>>>>>
>>>>> [1] http://hevayo.github.io/restful-apim/
>>>>>
>>>>> On Sat, Mar 28, 2015 at 12:47 AM, Frank Leymann <fr...@wso2.com>
>>>>> wrote:
>>>>>
>>>>>> Hi Jo,
>>>>>>
>>>>>> again, thanks for your work: we'll get a nice RESTful API :-) In
>>>>>> the Richardson maturity model we'll get to level 2 (not level 3 because
>>>>>> we
>>>>>> are leaving out HATEOS - which is something that is not used often today
>>>>>> in
>>>>>> practice anyhow).
>>>>>>
>>>>>> I exported the YAML of the API, put it into a Word document and used
>>>>>> the "change tracking" feature to comment/modify across the document -
>>>>>> please find the document attached. (Frank Input - API Manager API -
>>>>>> 2015-03-27.docx)
>>>>>>
>>>>>> All the changes I made to YAML itself is in the separate swagger YAML
>>>>>> file I attached too. I used the swagger 2.0 tool to create this YAML,
>>>>>> and
>>>>>> the tool shows no syntax errors... So you may import it into your tool
>>>>>> without problems. (FL Input API Manager API - 2015-03-27.yaml)
>>>>>>
>>>>>> I worked on the apis of the /apis and /apis/{apiID} resources. Before
>>>>>> I continue, I suggest that we have a discussion (i.e. a call) to discuss
>>>>>> the changes/suggestions I made. We need to agree whether this fits into
>>>>>> the
>>>>>> plan for implementing in the next release.
>>>>>>
>>>>>> Looking forward....
>>>>>>
>>>>>>
>>>>>>
>>>>>> Best regards,
>>>>>> Frank
>>>>>>
>>>>>> 2015-03-26 4:52 GMT+01:00 Joseph Fonseka <jos...@wso2.com>:
>>>>>>
>>>>>>> Hi Frank
>>>>>>>
>>>>>>> What are the headers we should include ?
>>>>>>>
>>>>>>> 1. For the access token header we can define it globally in the
>>>>>>> security definition [1]
>>>>>>> <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject>
>>>>>>> 2. Content-type headers are covered by the consumes and produces
>>>>>>> attributes [2]
>>>>>>> <https://github.com/hevayo/restful-apim/blob/master/apim.yaml#L18-L19>
>>>>>>> 3. For post methods we have an option of sending "Link" header with
>>>>>>> a URL to newly created resource rather than returning newly created
>>>>>>> resource JSON.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Jo
>>>>>>>
>>>>>>> [1]
>>>>>>> https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject
>>>>>>>
>>>>>>> [2]
>>>>>>> https://github.com/hevayo/restful-apim/blob/master/apim.yaml#L18-L19
>>>>>>>
>>>>>>> On Wed, Mar 25, 2015 at 3:51 PM, Frank Leymann <fr...@wso2.com>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Hi Jo,
>>>>>>>>
>>>>>>>> nice piece of work!
>>>>>>>>
>>>>>>>> What is still needed is a description of the header fields for
>>>>>>>> both, the requests and APIs.
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> Best regards,
>>>>>>>> Frank
>>>>>>>>
>>>>>>>> 2015-03-24 17:34 GMT+01:00 Joseph Fonseka <jos...@wso2.com>:
>>>>>>>>
>>>>>>>>> Hi All
>>>>>>>>>
>>>>>>>>> We are planing to implement a RESTFul API to expose the API
>>>>>>>>> Manager functionality. This will be a replacement to the currently
>>>>>>>>> provided
>>>>>>>>> Store and Publisher APIs [1]
>>>>>>>>> <https://docs.wso2.com/display/AM180/Publisher+APIs> & [2]
>>>>>>>>> <https://docs.wso2.com/display/AM180/Store+APIs>.
>>>>>>>>>
>>>>>>>>> Main Motivation.
>>>>>>>>> 1. The current APIs are not RESTful and they do not cover all the
>>>>>>>>> functionality.
>>>>>>>>> 2. To make it easy to integrate and automate API manager
>>>>>>>>> functionality with 3rd party systems.
>>>>>>>>> 3. To provide better security with Oauth.
>>>>>>>>> 4. To provide better versioning and documentation with the API.
>>>>>>>>>
>>>>>>>>> As a start we have written a draft version of the API definition
>>>>>>>>> which you can find here [3]
>>>>>>>>> <http://hevayo.github.io/restful-apim/>.
>>>>>>>>>
>>>>>>>>> Following is a rough implementation plan.
>>>>>>>>> 1. Work on the API Definition, get feed back from users and
>>>>>>>>> finalize.
>>>>>>>>> 2. Implementation. ( Architecture , Jax-RS ?)
>>>>>>>>> 3. Adding Security. ( O-auth, scopes ? )
>>>>>>>>> 4. Testing.
>>>>>>>>> 5. Documentation.
>>>>>>>>>
>>>>>>>>> API definition was written with Swagger 2 once completed we can
>>>>>>>>> use it to generate server stubs, client stubs and documentation.
>>>>>>>>>
>>>>>>>>> Please share your thoughts.
>>>>>>>>>
>>>>>>>>> Thanks
>>>>>>>>> Jo
>>>>>>>>>
>>>>>>>>> [1] https://docs.wso2.com/display/AM180/Publisher+APIs
>>>>>>>>> [2] https://docs.wso2.com/display/AM180/Store+APIs
>>>>>>>>> [3] http://hevayo.github.io/restful-apim/
>>>>>>>>>
>>>>>>>>> --
>>>>>>>>> *Joseph Fonseka*
>>>>>>>>> WSO2 Inc.; http://wso2.com
>>>>>>>>> lean.enterprise.middleware
>>>>>>>>>
>>>>>>>>> mobile: +94 772 512 430
>>>>>>>>> skype: jpfonseka
>>>>>>>>>
>>>>>>>>> * <http://lk.linkedin.com/in/rumeshbandara>*
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>>
>>>>>>> --
>>>>>>> *Joseph Fonseka*
>>>>>>> WSO2 Inc.; http://wso2.com
>>>>>>> lean.enterprise.middleware
>>>>>>>
>>>>>>> mobile: +94 772 512 430
>>>>>>> skype: jpfonseka
>>>>>>>
>>>>>>> * <http://lk.linkedin.com/in/rumeshbandara>*
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>>
>>>>> --
>>>>> *Joseph Fonseka*
>>>>> WSO2 Inc.; http://wso2.com
>>>>> lean.enterprise.middleware
>>>>>
>>>>> mobile: +94 772 512 430
>>>>> skype: jpfonseka
>>>>>
>>>>> * <http://lk.linkedin.com/in/rumeshbandara>*
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Architecture mailing list
>>>>> Architecture@wso2.org
>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> With regards,
>>>> *Manu*ranga Perera.
>>>>
>>>> phone : 071 7 70 20 50
>>>> mail : m...@wso2.com
>>>>
>>>> _______________________________________________
>>>> Architecture mailing list
>>>> Architecture@wso2.org
>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>>
>>>>
>>>
>>>
>>> --
>>>
>>> --
>>> *Joseph Fonseka*
>>> WSO2 Inc.; http://wso2.com
>>> lean.enterprise.middleware
>>>
>>> mobile: +94 772 512 430
>>> skype: jpfonseka
>>>
>>> * <http://lk.linkedin.com/in/rumeshbandara>*
>>>
>>>
>>> _______________________________________________
>>> Architecture mailing list
>>> Architecture@wso2.org
>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>
>>>
>>
>> _______________________________________________
>> Architecture mailing list
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
>
> --
>
> Thanks & regards,
> Nirmal
>
> Senior Software Engineer- Platform Technologies Team, WSO2 Inc.
> Mobile: +94715779733
> Blog: http://nirmalfdo.blogspot.com/
>
>
>
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
