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/>
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
