Hi all,
I am working on a new feature ‘API Categories’. It is very similar to tag
wise grouping in store from a store UI POV but has the following
differences w.r.t tags.
1. Categories define a broader collection of APIs. Tags can be used by the
publisher to emphasize specific details of an API.
2. Categories have to be pre-defined by an Admin before they can be
associated with any APIs.
3. Categories can have any valid string as their category name. Whereas tag
wise groups must have the suffix -group to be identified as a tag group.
In order to support this in APIM, I thought of using the following approach.
1. Define a REST API to do operations on category resources. Sample GET and
POST resources would be as below.
*"/categories"*: { *"get"*: { *"x-scope"*: *"apim:category_read"*,
*"x-wso2-request"*: *"GET
https://localhost:9443/api/am/admin/v0.15/categories
<https://localhost:9443/api/am/admin/v0.15/categories>**\n**Authorization:
Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8**\n**"*,
*"x-wso2-curl"*: *"curl -k -H **\"**Authorization: Bearer
ae4eae22-3f65-387b-a171-d37eaa366fa8**\"
\"**https://localhost:9443/api/am/admin/v0.15/categories
<https://localhost:9443/api/am/admin/v0.15/categories>**\"**"*,
*"x-wso2-response"*: *"HTTP/1.1 200 OK**\r\n**Content-Type:
application/json**\r\n\r\n**{**\r\n \"**count**\"**:1,**\r\n
\"**list**\"**:[**\r\n* *{**\r\n
\"**id**\"**:**\"**463e2c9f-5e99-43c3-a66e-de7e0f367373**\"**,**\r\n
\"**name**\"**:**\"**Finance**\"**,**\r\n
\"**description**\"**:**\"**Finance related APIS**\"\r\n*
*}**\r\n* *]**\r\n**}"*, *"summary"*: *"Get all API categories"*,
*"description"*: *"Get all API categories**\n**"*, *"tags"*: [
*"Category Collection"* ], *"responses"*: { *"200"*: {
*"description"*: *"OK.**\n**Categories returned**\n**"*,
*"schema"*: { *"$ref"*: *"#/definitions/**Category**List"*
} } } }, *"post"*: { *"x-scope"*:
*"apim:category_manage"*, *"x-wso2-curl"*: *"curl -k -X POST -H
**\"**Authorization: Bearer 0d63e133-7ad6-3aeb-9ca9-9299e0708122**\"*
*-H **\"**Content-Type: application/json**\"*
*https://apis.wso2.com/api/am/admin/v0.15/
<https://apis.wso2.com/api/am/admin/v0.15/>**categorie**s -d
@data.json"*, *"x-wso2-request"*: *"POST
https://localhost:9443/api/am/admin/v0.15/categories
<https://localhost:9443/api/am/admin/v0.15/categories>**\r\n**Authorization:
Bearer 0d63e133-7ad6-3aeb-9ca9-9299e0708122**\r\n**Content-Type:
application/json**\r\n\r\n* *-d {**\r\n
\"**name**\"**:**\"**Finance**\"**,**\r\n
\"**description**\"**:**\"**Finance related APIS**\"\r\n* *}"*,
*"x-wso2-response"*: *"HTTP/1.1 201 Created**\r\n**Content-Type:
application/json**\r\n\r\n**{**\r\n \"**count**\"**:1,**\r\n
\"**list**\"**:[**\r\n* *{**\r\n
\"**id**\"**:**\"**463e2c9f-5e99-43c3-a66e-de7e0f367373**\"**,**\r\n
\"**name**\"**:**\"**Finance**\"**,**\r\n
\"**description**\"**:**\"**Finance related APIS**\"\r\n*
*}**\r\n* *]**\r\n**}"*, *"summary"*: *"Add a Category"*,
*"description"*: *"Add a new API Category**\n**"*, *"parameters"*:
[ { *"in"*: *"body"*, *"name"*: *"body"*,
*"description"*: *"Category object that should to be added**\n**"*,
*"required"*: *true*, *"schema"*: { *"$ref"*:
*"#/definitions/Category"* } } ], *"tags"*: [
*"Category"* ], *"responses"*: { *"201"*: {
*"description"*: *"Created.**\n**Successful response with the newly
created object as entity in the body.**\n**"*, *"schema"*: {
*"$ref"*: *"#/definitions/Category"* } },
*"400"*: { *"description"*: *"Bad Request.**\n**Invalid request
or validation error**\n**"*, *"schema"*: { *"$ref"*:
*"#/definitions/Error"* } } } }}
And category and categoryList would be defined as below.
*"Category"*: { *"title"*: *"Category"*, *"required"*: [
*"name"* ], *"properties"*: { *"id"*: { *"type"*:
*"string"*, *"example"*:
*"01234567-0123-0123-0123-012345678901"* }, *"name"*: {
*"type"*: *"string"*, *"example"*: *"Finance"* },
*"description"*: { *"type"*: *"string"*, *"example"*:
*"Finance related APIs"* } } }, *"CategoryList"*: {
*"title"*: *"Category List"*, *"properties"*: { *"count"*: {
*"type"*: *"integer"*, *"description"*: *"Number of
categories returned.**\n**"*, *"example"*: 1 },
*"list"*: { *"type"*: *"array"*, *"items"*: {
*"$ref"*: *"#/definitions/Category"* } } } }}
2. Define a new AM_CATEGORIES table to hold category related details.
*CREATE TABLE *IF *NOT EXISTS *AM_CATEGORIES ( CATEGORY_ID
*VARCHAR*(50), NAME *VARCHAR*(255), DESCRIPTION *VARCHAR*(1024),
TENANT_DOMAIN *VARCHAR*(255), *UNIQUE *(NAME,TENANT_DOMAIN),
*PRIMARY KEY *(CATEGORY_ID));
3. Publisher UI overview tab(or a suitable place as it fits) will have a
new UI element to select categories for the API. And selecting categories
for an API would be optional.
4. API to category mapping will be stored in registry API artifact and for
that following table field would have to be added to api.rxt. (I assume we
are going to support associating a single API with multiple categories)
<table name="Categories" columns="1" maxoccurs="unbounded">
<subheading>
<heading>Category Name</heading>
</subheading>
<field type="text">
<name label="Category Name">categoryName</name>
</field>
</table>
5. And from store viewing POV, I assume API categories are a substitution
for existing tag-wise grouping feature and that both tag-wise groups and
categories won’t co-exist in the store. Please do correct if my
understanding is wrong.
Once a developer visits the store, he will be presented with the list of
API categories and upon selecting a category out of those, associated APIs
will be listed.
APIs that are not associated with any category will be listed under other
APIs or a similar heading.
Please feel free to add your suggestions.
Thanks,
Sachini
--
*Sachini De Silva*
Senior Software Engineer - WSO2
Email : [email protected]
Mobile : +94714765495
_______________________________________________
Dev mailing list
[email protected]
http://wso2.org/cgi-bin/mailman/listinfo/dev
