Hi All
Please find the latest API definition @ [1]
<http://hevayo.github.io/restful-apim/#/> with the following changes.
1. All the resources are updated with the relevant HTTP headers and
responses proposed by Frank.
2. Added search condition grammar for API search.
3. Added next page and previous page for "List" models
4. Added operational resource for updating tier permissions sent by
Sanjeewa.
Some more issues to discuss
1. Currently API Id is made from a composite key
including (name/version/provider). In the REST API we thought of passing
the API ID as a concatenated string with the above 3 attributes delimited
by a special character ( thinking of + ). Is there a better approach to
handle this ?
2. Should we come up with application specific error codes to passed in
Error objects. Following are the benefits.
- Same HTTP error code can be mapped to two different errors (eg. in
/apis/{apiId}/document/{documentId} can return 404 if either api or
document missing )
- If client wants to localize errors he can do with error codes.
Please share your thoughts.
Thanks
Jo
[1] http://hevayo.github.io/restful-apim/#/
On Wed, Apr 1, 2015 at 6:35 PM, Sanjeewa Malalgoda <[email protected]>
wrote:
> Hi Jo,
> Here i have attached updated apim.yaml file with my suggestions.
> Lets merge that to latest code.
>
> Thanks,
> sanjeewa.
>
> On Wed, Apr 1, 2015 at 1:55 PM, Sanjeewa Malalgoda <[email protected]>
> wrote:
>
>> Hi All,
>>
>> Here are my suggestions on this implementation.
>> When we design rest API for API Management functionality we need to focus
>> bit on publisher/ store aspects as well. Or we may need to have control at
>> some point based on the logged in user.
>> Here is one example:
>>
>> /apis
>> GET /apis
>> API provider should be mandatory field when it comes to publisher context.
>> API consumer should be mandatory field when it comes to store context.
>> Or we should be able to retrieve current user by using JWT comes with
>> request or from access token. Still need to if request comes to store or
>> publisher context.
>>
>> And based on current user permissions we may need enable, disable API
>> add/modification via post, put, delete.
>>
>> Also for tiers we may have
>>
>> /tiers
>>
>> post
>> /tiers/{tierName}/update-permission
>>
>> Request body
>> {
>> "rolePermission": {
>> "access": "",
>> "roles": ""
>> }
>> }
>>
>>
>> Also for apis/{apiId} PUT need to have response with 409 Conflict as
>> well. Normally when we update resource with some information it cannot be
>> accessed due to some reason. So IMO having 409 as well would be helpful(in
>> addition to 412)
>>
>> It would be ideal /apis/{apiId}/change-lifecycle success response returns
>> 200 status code as we normally use 201 to indicate that new resource
>> created.
>> In this particular case we do update for existing resource state.
>>
>> We may include additional response code to /apis/{apiId}/documents GET
>> because we may have 2 situations.
>> 01. API does not exists(We can consider 412 for response code)
>> 02. API exists but documents not available(we can consider 404 as
>> requested resource is document).
>>
>> And same should apply to /apis/{apiId}/documents/{documentId} GET as well.
>>
>> And we need to finalize about security model for this rest API. For that
>> we may consider few options.
>>
>> 01. Oath2 secured API.
>> 02. Basic auth secured rest API.
>> 03. Other security mechanisms.
>>
>> My personal opinion is this rest API should be independent from security
>> protocol.
>> And our rest API should not rely on any security related information when
>> in process request.
>> If we need to verify user is having permission to do some task then we
>> should not do it in rest API level(api subscriber should not allow to
>> update API).
>>
>>
>> Thanks,
>> sanjeewa.
>>
>> On Tue, Mar 31, 2015 at 11:07 PM, Joseph Fonseka <[email protected]> wrote:
>>
>>> Hi Frank
>>>
>>> Yes 2pm is fine for me, my skype is "jpfonseka". Will ask "Sanjeewa
>>> Malalgoda" to join as well he was working on the ground work for the
>>> implementation.
>>>
>>> Thanks & Regards
>>> Jo
>>>
>>>
>>>
>>> On Tue, Mar 31, 2015 at 5:03 PM, Frank Leymann <[email protected]> wrote:
>>>
>>>> Hi Jo,
>>>>
>>>> is it possible for you to have a call tomorrow, Wednesday, 4/1, 2pm
>>>> Colombo time (i.e. 10:30am Germany, daylight-savings-time). I thing a
>>>> 30...60 minutes will be suffice. Main purpose would be how to proceed :-)
>>>>
>>>> I find Skype more reliable than Hangouts. Would you mind about a Skype
>>>> call? My SkypeID is frank.leymann
>>>>
>>>> Talk to you then!
>>>>
>>>>
>>>> Best regards,
>>>> Frank
>>>>
>>>> 2015-03-30 13:03 GMT+02:00 Joseph Fonseka <[email protected]>:
>>>>
>>>>> 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 <[email protected]>
>>>>> 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 <[email protected]>:
>>>>>>
>>>>>>> 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 <[email protected]>
>>>>>>> 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 <[email protected]>:
>>>>>>>>
>>>>>>>>> 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>*
>>>>>
>>>>>
>>>>
>>>
>>>
>>> --
>>>
>>> --
>>> *Joseph Fonseka*
>>> WSO2 Inc.; http://wso2.com
>>> lean.enterprise.middleware
>>>
>>> mobile: +94 772 512 430
>>> skype: jpfonseka
>>>
>>> * <http://lk.linkedin.com/in/rumeshbandara>*
>>>
>>>
>>
>>
>> --
>>
>> *Sanjeewa Malalgoda*
>> WSO2 Inc.
>> Mobile : +94713068779
>>
>> <http://sanjeewamalalgoda.blogspot.com/>blog
>> :http://sanjeewamalalgoda.blogspot.com/
>> <http://sanjeewamalalgoda.blogspot.com/>
>>
>>
>>
>
>
> --
>
> *Sanjeewa Malalgoda*
> WSO2 Inc.
> Mobile : +94713068779
>
> <http://sanjeewamalalgoda.blogspot.com/>blog
> :http://sanjeewamalalgoda.blogspot.com/
> <http://sanjeewamalalgoda.blogspot.com/>
>
>
>
--
--
*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
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
