externally consumable REST API

[theroys]

Creating an external user specific REST API ,whereby OSSRank will provide ranking and other metadata to outside world

[fsiddiqi]

+1, this will be an extension of the current API

Existing REST APIs:

• /api/projects
• /api/projects/{id}
• /api/categories
• /api/categories/{id}
• /api/search

Ideas:

• Since this API is growing, we can start design REST resources in swagger and publish as API doc
• Extend to query and filter each resource

Please add ideas

[sorin-costea]

The current "API" search-like call
/api/category_map?category=somecategory
could be replaced with somehing like:
/api/categories/{id}/projects

[sorin-costea]

As an idea, also the real search
/api/search?term=searchterm
could use instead:
/api/categories?keywords=searchterm

[sorin-costea]

Especially the projects could use pagination (1-based, default size 100):
/api/projects?page=1&pagesize=100
/api/categories/{id}/projects?page=1&pagesize=100

[sorin-costea]

What is returned by
/api/category_map?category=somecategory
and by the
/api/projects?tages=sometag
should be the same thing (a partial projects response), like:

{
    "projects": [
    {
        "_id": {
        "$oid": "559ac491e4b0a61755104a8d"
        }, 
        "_rank": 9483, 
        "description": "", 
        "name": "angular"
    }, 
    {

[sorin-costea]

Results lists could be accompaned by the results size:

{
    "categories": [],
    "size": 0
}

[sorin-costea]

Is there a strong reason to have some fields prefixed with an underscore?

[sorin-costea]

Errors objects should be standalone reply objects - not just cram error messages inside regular answers like this answer from http://localhost:8080/api/projects?filter=1&tags=angular|java

{
  "projects": {
    "class": "com.mongodb.MongoException$Network", 
    "message": "Read operation to server blahblah.mongolab.com:12345 failed on database ossrank", 
    "stackTrace": [...

[fsiddiqi]

underscore prefix explanation: we're adding these elements to existing JSON structures received from various APIs. The underscore was a convention to easily identify these attributes. Alternatives welcome

[sorin-costea]

Ok fine with the underscores - how about we also document why :)