Shall we use "API Categories" everywhere instead of just "Categories"? Because in the future there can be other category types too.
Thanks, Bhathiya On Wed, Nov 13, 2019 at 10:59 AM Sachini De Silva <[email protected]> wrote: > 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 > > -- *Bhathiya Jayasekara* | Technical Lead | WSO2 Inc. (m) +94 71 547 8185 | (e) bhathiya-@t-wso2-d0t-com
_______________________________________________ Dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/dev
