Create tags/categories for APIs

[IvanGoncharov]

It's very easy to add some OpenAPI extension like x-categories.
But in order to tag every API a lot of manual work required.
If someone volunteers to do this work I can provide instruction and write all necessary code.

[sanchojaf]

Hi Ivan, I'm interesting in do this work, please send me the instructions.
Thanks

[IvanGoncharov]

Cool 👍
Most important is the right set of tags, I will look into APIs.io or ProgramableWeb for such sets.
Maybe you know of any other sources for API tags/categories?

[MikeRalphson]

APIforthat uses the following categories:

Search
Backend
Social
Tools
Financial
Enterprise
Entertainment
Security
Database
Maps
Education
Health
Music
Shopping
Blogging
Storage
Photos
Messaging
Weather

[sanchojaf]

Well I had a similar problem for https://cenit.io/directory, I reviewed ProgramableWeb, Zapier and other sources.

That is the tags that we have (each one with more that 5 items in the directory):

Accounting
Advertising
Analytics
Backend
Billing
Blogging
Bookmarks
Business
Calendars
Charting
Chat
Cloud Platform
Cloud Storage
Cms
Code Review
Collaboration
Continuous Integration
Crm
Customer Support
Dashboard
Database
Developer Tools
Digital Signature
Ecommerce
Education
Email
Email Marketing
Enterprise
Erp
Error Tracking
Event Management
File Management
Financial
Forms
Help Desk
Hosting
Internet Of Things
Issue Tracking
Jobs
Lead Generation
Location
Marketing
Messaging
Mobile
Monitoring
Nlp
Notifications
Office
Other
Package Management
Payment Processing
Personal Information Management
Phone
Photos
Project Management
Real Estate
Reference
Search
Sentiment Analysis
Server Monitoring
Social
Storage
Surveys
Telephony
Time Tracking
Tools
Translation
Version Control
Video

Some case are redundant, and could be improve.

I think that is important use multi-tag classification.

[sanchojaf]

Some source of tags that we can use like references:

this first link I think that is a good reference:

• https://github.com/api-stack/api-stack/blob/gh-pages/data/tags.json (http://theapistack.com/apis.json here if you enter in a particular url, you will see the tags)

others:

• https://zapier.com/zapbook/
• https://ifttt.com/channels#all
• https://www.cloudpipes.com/channels
• http://www.programmableweb.com/category
• http://www.apiforthat.com/apis?category=Search
• https://cenit.io/directory

[IvanGoncharov]

@sanchojaf Very cool.
One thing that I don't like is capitalization of acronyms like Nlp, Crm, Cms, etc.
I think they should be NLP, CRM, CMS, etc.

Another is Other category can you give examples of APIs that you will assign to it?
Maybe it could be renamed to Utils?

I think that is important use multi-tag classification.

I don't have any strong opinion about that, so let's ask more people.
@sanchojaf @MikeRalphson @bobby-brennan @RomanGotsiy @mittsh @oliver-xapix-io @darklynx
What do you think?
I see 3 possible options:

• keywords - each API has array of arbitrary strings
• tags - each API has array of strings from fixed set
• categories - each API has single string from fixed set

We can also do some hybrid solutions, for e.g. categories + keywords, but it will require more work to maintain.

[sanchojaf]

Yes I agree with: NLP, CRM, CMS, and with ovoid 'Other'.

+1, by tags

[oliver-xapix-io]

I'd appreciate tags + keywords as described last by @IvanGoncharov

[mittsh]

Why not having keywords (include brands, services names, or anything...) + categories (fixed set of kind of APIs as listed above). I think both keywords and categories are subsets of tags. So why not having 2 arrays, one categories one keywords.

Also for having all tags lowercases (e.g. nlp, instagram, etc.) so searches will be inherently case-insensitive.

Love the idea of these tags/categories/keywords :)

[MikeRalphson]

Is it worth stating explicitly what the expected use case is for tags/categories/keywords?

My gut feeling would be to go with one category (what the API is, where it is, e.g. in a directory or menu structure) and an array of tags or keywords (how to find the API). We could define the categories, then the tags/keywords would be the set of categories (for alternatives to the main category) + any other tag/keyword value.

+1 for correct capitalisation of acronyms.

[RomanHotsiy]

First of all, let's agree on terms we use because there's some mess:

• keywords - each API has array of arbitrary strings
• tags - each API has array of strings from fixed set
• categories - each API has single string from fixed set

So I agree with @MikeRalphson that we should start from use cases.
The one of the main use cases is grouping APIs (e.g. here). Although we can group APIs by tags I believe we should have a category (only one category) to prevent duplications in groups.

For sure we should have either tags or keywords in addition to the category. I don't have the strong opinion about tags vs keywords.

+1 for correct capitalisation of acronyms.
-1 for lowercase: the usecase of grouping includes the need to display group names somewhere + we can always lowercase capitalized string but not vice versa.

[sanchojaf]

I don't like very much the idea of a main category, is rigid a classification, and sometime have issues when properties of an item belong to more that one class. Duplications in groups is not necessary a problem. For other side I recognize that have a simple classification system is more easy for maintain.

Examples:

• Google analytic: Analytics | Ecommerce | Charting
• Google drive: Cloud Storage | File Management
• Ontraport: CRM | Ecommerce | Marketing
• Semantria: NLP |Sentiment Analysis
• Youtube: Video | Social
• Blogger: Social | CMS

[RomanHotsiy]

Duplications in groups is not necessary a problem

Agree, actually, duplications is not a big problem in comparison to choosing only one main category for each API

[IvanGoncharov]

I will try to summarise discussion in more formal proposal:
We will have x-APIs.guru-tags which is an array of strings from fixed set.
APIs.guru prefixes needed since the list is maintained by this project.
The order will be significant so most important is the first tag and the last one is least important.
For example Youtube will have value:

x-APIs.guru-tags:
  - Video
  - Social

And for Blogger:

x-APIs.guru-tags:
  - Social
  - CMS

So when user clicks on Social in menu he first sees APIs which have this tag as the first element,
Blogger in this example. Down the list there would be APIs which have Social tag as the second element, and so on.

Tags names are optimised to be directly presented to the user, for example CRM, eCommerce, etc.
At some point tag name should be converted to the form which looks good to the user.
Each client can do their own mapping for tag names but it's important to have the default one.
You can always convert tags to lower case but the reverse transformation is impossible.

At the same time, we support optional x-keywords with no restriction on values.

@sanchojaf @MikeRalphson @bobby-brennan @RomanGotsiy @mittsh @oliver-xapix-io @darklynx
Please comment on this.

[IvanGoncharov]

One more things, I will add validation check for tag names, so they always are from the same set and with the same letter case. If somebody adds Nlp instead of NLP it will result in the validation error.

[MikeRalphson]

Will you add all tags and keywords as patches, or would you want APIs.guru-aware APIs to add them to the source?

[IvanGoncharov]

Will you add all tags and keywords as patches, or would you want APIs.guru-aware APIs to add them to the source?

It makes sense to add x-keywords to the source since anybody can use it and there is nothing APIs.guru specific.

But x-APIs.guru-tags is too specific and it's better to keep it local to this repo.
Also, it will allow adding a new tag and marking APIs with it as one PR.
Note: Deleting tag or changing its name is breaking change but adding a new one isn't.

[IvanGoncharov]

Let's wait a day to hear more feedback before starting to discuss the list of tags.

[rbren]

This sounds good to me, will definitely help with organizing any-api.com. x-APIs.guru-tags is a little hard to read though. Maybe just use an x-APIs.guru object? i.e.

{
  "info": {"title": "My API"},
  "x-APIs.guru": {
    "tags": ["foo", "bar"]
  }
}

One question: how should I go about utilizing both x-keywords and x-APIs.guru-tags? Should I merge them into one list?

[darklynx]

I like the idea to support tags and keywords. Tags allow to group APIs into a list of known categories, the list is fixed (or slowly growing) so that developers can not reintroduce the same category under slightly different name by mistake. Keywords are important to those developers who are not satisfied with standard set of tag values and would like to add additional markers.

I also like the idea of tag weight bound to the natural order in the list of tags - simple, clean, and consistent. In this case keywords cannot be mixed with tags though and they should be used for different use cases: e.g to display main categories - tags only, to apply in search results or display a keywords cloud - tags + keywords

I personally would prefer a set of lower cased single word tags :) (I'm a programmer and I know the advantages of such set, e.g. the localization of tags in this case could be a simple Map/Hashtable in many programming languages) but I'm fine if you decide for human readable set of tags with preferred natural capitalization.

[rbren]

I agree with using lowercase and underscore tags. You can then serve tags.json from the APIs.guru API to provide titles and descriptions for each tag, e.g.

{
  "social": {
    "title": "Social",
    "description": "Interact with social networks and share media"
  }
}

[sanchojaf]

1+ for lowercase and underscore too

1+ tags.json:

• key: name with lowercase and underscore (internet_of_things, nlp)
• title: Using capitalization of names.
• slug: URL user-friendly name (internet-of-things, nlp)
• description: optional

e.g.

{
        "internet_of_things": {
                        "title": "Internet of Things",
                        "slug": "internet-of-things"
        },
        "nlp": { 
                        "title": "NLP",
                        "slug": "nlp",
                        "description": "Natural Language Processing"
                }
} 

[IvanGoncharov]

Summary after second round:
We will have x-APIs.guru-tags which is an array of strings from fixed set.
The order will be significant so most important is the first tag and the last one is least important.
At the same time, we support optional x-keywords with no restriction on values.

Tags names are optimised to be directly presented to the user, for example CRM, eCommerce, etc.
Tag names consist of following symbols a-z_. For each tag user-friedly title and description provided.
Repo will have YAML file, in API it will be exposed both as YAML and JSON:

iot:
  title: 'IoT'
  description: 'Internet of Things'
nlp: 
  title: 'NLP'
  description: 'Natural Language Processing'

@sanchojaf If we support tags from small set, then we should provide description for all of them.
If algorithm for creating slug is replacing _ with -, it overkill to provide them as part of API or I missing something?

Next step would be to create initial list of tags as resources/tags.yaml file.
@sanchojaf If you have time, can you please make PR with it?
Making it as PR allow attach comment to every line.

[sanchojaf]

@IvanGoncharov I agree with your summary, yes I can do a PR.

[sanchojaf]

Hi All, let me know any feedback with initial list of tags.json, I know that could be improved a lot #61

[IvanGoncharov]

I read Wiki article about tag and couple of articles about tag vs keyword.

TL;DR
In information systems, a tag is a non-hierarchical keyword or term assigned to a piece of information. Tags are generally chosen informally and personally by the item's creator or by its viewer, depending on the system.

Tags: An On-Site Filing System
Keywords: A Search Engine's Way of Classifying Webpages

And it looks like I confuse few things so change names of extensions:
x-APIs.guru-tags => x-APIs.guru-categories x-apisguru-categories
x-keywords => x-tags

Since automatic extraction of keywords from Swagger is definitely a possibility in a future, it's better to use x-tags for manually assigned words.

I also marked APIs.guru API as an example:
https://github.com/APIs-guru/api-models/blob/master/APIs/apis-guru.github.io/patch.yaml

[MikeRalphson]

@IvanGoncharov Could you add a 'suggested categories' input to your Add API form, maybe with a link to the list of categories (I can put that on the wiki)? This will help me remember to add categories to new APIs.

Please also let me know if you'd prefer an issue on a different repo for website-related issues?

[IvanGoncharov]

@MikeRalphson For a time being this form live here: https://github.com/APIs-guru/APIs-guru.github.io
So I think it's better to open issues there and assign them to @RomanGotsiy
Since he is the true mastermind behind our website.

P.S. I think this issue can be closed since absolute majority of APIs are tagged.

[MikeRalphson]

Closing as above. Many thanks everyone, especially @LucyBot-Andrew !