[Backend] Improvements - Githubissues

Twentysix26 commented 7 years ago

A few general suggestions (keep in mind I only played with the search endpoint so far):

Currently I have to urllib.parse.unquote the data I get. Example:
"name": "Helps%20you%20cover%20your%20DOTA%202%20needs" I think this should be done by the backend.
Perhaps a maxResults parameter for the search endpoint? Both for convenience and less strain on the API
I've only used the search endpoint so far but I think usability would benefit greatly in general if repo was a dict with name, url, etc... Perhaps author should be a dict too? But I'm not sure what could it contain other than the name.
Maybe provide direct links for the portal too? Example: https://cogs.red/cogs/cog/26-Cogs/cleverbot/ Not sure though, they're not that hard to build from the provided data, so it would mostly be in case of future changes I guess.

orels1 commented 7 years ago

Ok, I'm here

Legit complaint, API should return the result you can use, will decode on the backend
Well, considering the way I gather cogs list in my backend, i'm not sure it will really matter in terms of perfomance (basically, it will scan for all the results anyway), but I feel like it's just a quality of life improvement for the API user
repo is a dict oO not sure what you meant there, I mean:

{
         "_id": "21fsdkg9342ijhgh9sf0234",
         "name": "ORELS-Cogs",
         "author": "orels1",
         "short": "Mainly gaming/data oriented cogs",
         "description": "(orels1): Thanks for using my repo, hope you have fun!",
         "cogs": {
             "dota": {
                  "author": "orels1",
                  "short": "Gets you item builds, hero info and more",
                  "description": "Dota 2 cog will get you the top item and skill-builds for any hero in game, as well as stats for your latest match + a dotabuff link. Enjoy",
                  "install_msg": "(orels1): Have fun!"
              }
         },
         "parsed": true,
         "url": "https://github.com/orels1/ORELS-Cogs",
         "type": "approved"
     }

you mean like the _html field (on github's API) or something, that will lead to the page on cogs.red? I think at this point that will be good to put all the links into one dict like so:

...
"cogs": [{
        ...
        "links": {
            "self": "link/to/cog/on/cogs.red",
            "_self": "link/to/this/api/endpoint",
            "repo": "link/to/repo/on/cogs.red",
            "_repo": "link/to/repos/api/endpoint",
            "source": "link/to/cog/on/github",
            "github": "link/to/repo/on/github"
        }
        ...
    }]
...

Twentysix26 commented 7 years ago

Keep in mind that I only tested one endpoint, the search one, I'm not sure if the others are different. I'm basing my suggestion on that. There, each returned cog has repoUrl and repoType. I think there should be a repo dict instead, that contains the mentioned two fields plus repoName. (Well, I guess they could be called just url, type and name if it becomes a dict). About the links, yes, I meant something like that.

orels1 commented 7 years ago

Updated repo response structure

{
  "error": false,
  "results": {
    "_id": "587d62b4c54cad51845ae101",
    "name": "ORELS-Cogs",
    "__v": 4,
    "description": "Repository of mainly gaming/data based cogs, with a bit of some fun stuff. Use as you like.",
    "short": "Data scraping cogs with a bit of extra",
    "links": {
      "_self": "/api/v1/repo/ORELS-Cogs",
      "_update": "/api/v1/repo/ORELS-Cogs/fetch",
      "self": "cogs/repo/ORELS-Cogs/",
      "github": {
        "self": "https://github.com/orels1/ORELS-Cogs",
        "_update": "https://api.github.com/repos/orels1/ORELS-Cogs/contents/info.json?ref=master"
      }
    },
    "type": "unapproved",
    "parsed": false,
    "cogs": [],
    "author": {
      "name": "orels",
      "url": "https://github.com/orels1"
    }
  }
}

Updated cog response structure

{
  "links": {
    "github": {
      "_update": "https://api.github.com/repos/orels1/ORELS-Cogs/contents/dota/info.json?ref=master",
      "repo": "https://github.com/orels1/ORELS-Cogs",
      "self": "https://github.com/orels1/ORELS-Cogs/blob/master/dota/dota.py"
    },
    "repo": "cogs/repo/ORELS-Cogs/",
    "self": "/cogs/cog/ORELS-Cogs/dota/",
    "_update": "/api/v1/cogs/cog/ORELS-Cogs/dota/fetch",
    "_repo": "/api/v1/repo/ORELS-Cogs",
    "_self": "/api/v1/cogs/cog/ORELS-Cogs/dota"
  },
  "description": "Requires tabulate, dota2py and beautfulSoup\nInstall with:\npip3 install bs4\npip3 install dota2py\npip3 install tabulate\n\nAlso requires dota 2 api key, which you can get here: http://steamcommunity.com/dev/apikey\nYou will need to set your key with [p]dota setkey command in PM\n\nUsage:\n[p]dota hero <hero>\n Shows info about hero\n[p]dota build <hero>\n Shows most popular skillbuild\n[p]dota items <hero>\n Shows most popular items\n[p]dota online\n Shows amount of players online\n[p]dota recent <steamID>\n Shows info about the latest dota match",
  "short": null,
  "author": {
    "url": "https://github.com/orels1",
    "name": "orels"
  },
  "repo": {
    "type": "unapproved",
    "name": "ORELS-Cogs"
  },
  "name": "dota"
}

orels1 commented 7 years ago

For search added limit and offset, looks like this:

/api/v1/cogs/search/info?limit=3&offset=2

I think they're pretty self-explanatory :P They don't really help me, since currently I'm still doing aggregation for the whole thing, but i think this can make API more useful, so you could ask for other results and get the next 3 matches by setting

?limit=3&offset=3

orels1 / Red-Portal

[Backend] Improvements #6