Comments (29)
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.
from openapi-directory.
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.
from openapi-directory.
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
from openapi-directory.
Yes I agree with: NLP, CRM, CMS, and with ovoid 'Other'.
+1, by tags
from openapi-directory.
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.
from openapi-directory.
APIforthat uses the following categories:
Search Backend Social Tools Financial Enterprise Entertainment Security Database Maps Education Health Music Shopping Blogging Storage Photos Messaging Weather
from openapi-directory.
I'd appreciate tags + keywords as described last by @IvanGoncharov
from openapi-directory.
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 :)
from openapi-directory.
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.
from openapi-directory.
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.
from openapi-directory.
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.
from openapi-directory.
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"
}
}
from openapi-directory.
Hi All, let me know any feedback with initial list of tags.json, I know that could be improved a lot #61
from openapi-directory.
@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.
from openapi-directory.
Hi Ivan, I'm interesting in do this work, please send me the instructions.
Thanks
from openapi-directory.
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?
from openapi-directory.
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
from openapi-directory.
@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.
from openapi-directory.
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.
from openapi-directory.
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
from openapi-directory.
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
from openapi-directory.
Will you add all tags and keywords as patches, or would you want APIs.guru-aware APIs to add them to the source?
from openapi-directory.
Let's wait a day to hear more feedback before starting to discuss the list of tags.
from openapi-directory.
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?
from openapi-directory.
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.
from openapi-directory.
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"
}
}
from openapi-directory.
@IvanGoncharov I agree with your summary, yes I can do a PR.
from openapi-directory.
@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?
from openapi-directory.
Closing as above. Many thanks everyone, especially @LucyBot-Andrew !
from openapi-directory.
Related Issues (20)
- Add "ETSI ETSI GS MEC 010-2 - LCM API" API
- Add "Meta Web Page Preview API" API
- Add "Remove Image Background" API
- Add "World News API" API
- Add "Humor API" API
- Add "API League" API
- Add "Novelai" API
- Add "LDE Business Listings API" API
- Add "LDE Entity Resolution API" API
- Add "LDE Business Reviews API" API
- Add "Amazon advertising product metadata api" API HOT 1
- Add "APITier - UK PostCode API" API
- Add "APITier - VAT API" API
- Add "PDFHub APIs for Converting documents into PDF, editing PDF documents and much more" API
- Add "IPinfo" API
- Add "Semantic Scholar" API HOT 1
- Add "One Auto API" API
- Urlscore API
- linode has non-standard discriminator
- Invalid exclusive{Maximum|Minimum} values in groundhog-day HOT 8
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from openapi-directory.