{"action":"created","issue":{"url":"https://api.github.com/repos/DOAJ/doaj/issues/752","labels_url":"https://api.github.com/repos/DOAJ/doaj/issues/752/labels{/name}","comments_url":"https://api.github.com/repos/DOAJ/doaj/issues/752/comments","events_url":"https://api.github.com/repos/DOAJ/doaj/issues/752/events","html_url":"https://github.com/DOAJ/doaj/issues/752","id":82458567,"number":752,"title":"Discovery API - Documentation","user":{"login":"emanuil-tolev","id":1190172,"avatar_url":"https://avatars.githubusercontent.com/u/1190172?v=3","gravatar_id":"","url":"https://api.github.com/users/emanuil-tolev","html_url":"https://github.com/emanuil-tolev","followers_url":"https://api.github.com/users/emanuil-tolev/followers","following_url":"https://api.github.com/users/emanuil-tolev/following{/other_user}","gists_url":"https://api.github.com/users/emanuil-tolev/gists{/gist_id}","starred_url":"https://api.github.com/users/emanuil-tolev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/emanuil-tolev/subscriptions","organizations_url":"https://api.github.com/users/emanuil-tolev/orgs","repos_url":"https://api.github.com/users/emanuil-tolev/repos","events_url":"https://api.github.com/users/emanuil-tolev/events{/privacy}","received_events_url":"https://api.github.com/users/emanuil-tolev/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/DOAJ/doaj/labels/api%20phase%201","name":"api phase 1","color":"bfe5bf"}],"state":"open","locked":false,"assignee":{"login":"Nimphal","id":4950775,"avatar_url":"https://avatars.githubusercontent.com/u/4950775?v=3","gravatar_id":"","url":"https://api.github.com/users/Nimphal","html_url":"https://github.com/Nimphal","followers_url":"https://api.github.com/users/Nimphal/followers","following_url":"https://api.github.com/users/Nimphal/following{/other_user}","gists_url":"https://api.github.com/users/Nimphal/gists{/gist_id}","starred_url":"https://api.github.com/users/Nimphal/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Nimphal/subscriptions","organizations_url":"https://api.github.com/users/Nimphal/orgs","repos_url":"https://api.github.com/users/Nimphal/repos","events_url":"https://api.github.com/users/Nimphal/events{/privacy}","received_events_url":"https://api.github.com/users/Nimphal/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/DOAJ/doaj/milestones/17","html_url":"https://github.com/DOAJ/doaj/milestones/API%20and%20Widgets","labels_url":"https://api.github.com/repos/DOAJ/doaj/milestones/17/labels","id":1125708,"number":17,"title":"API and Widgets","description":"","creator":{"login":"emanuil-tolev","id":1190172,"avatar_url":"https://avatars.githubusercontent.com/u/1190172?v=3","gravatar_id":"","url":"https://api.github.com/users/emanuil-tolev","html_url":"https://github.com/emanuil-tolev","followers_url":"https://api.github.com/users/emanuil-tolev/followers","following_url":"https://api.github.com/users/emanuil-tolev/following{/other_user}","gists_url":"https://api.github.com/users/emanuil-tolev/gists{/gist_id}","starred_url":"https://api.github.com/users/emanuil-tolev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/emanuil-tolev/subscriptions","organizations_url":"https://api.github.com/users/emanuil-tolev/orgs","repos_url":"https://api.github.com/users/emanuil-tolev/repos","events_url":"https://api.github.com/users/emanuil-tolev/events{/privacy}","received_events_url":"https://api.github.com/users/emanuil-tolev/received_events","type":"User","site_admin":false},"open_issues":28,"closed_issues":2,"state":"open","created_at":"2015-05-22T13:47:52Z","updated_at":"2015-06-29T13:37:06Z","due_on":"2015-09-30T23:00:00Z","closed_at":null},"comments":2,"created_at":"2015-05-29T14:48:19Z","updated_at":"2015-07-17T16:56:26Z","closed_at":null,"body":"- [ ] docs for #735 , the public search over journals and articles\r\n- [ ] docs for #751 , the authenticated search for applications"},"comment":{"url":"https://api.github.com/repos/DOAJ/doaj/issues/comments/122342355","html_url":"https://github.com/DOAJ/doaj/issues/752#issuecomment-122342355","issue_url":"https://api.github.com/repos/DOAJ/doaj/issues/752","id":122342355,"user":{"login":"emanuil-tolev","id":1190172,"avatar_url":"https://avatars.githubusercontent.com/u/1190172?v=3","gravatar_id":"","url":"https://api.github.com/users/emanuil-tolev","html_url":"https://github.com/emanuil-tolev","followers_url":"https://api.github.com/users/emanuil-tolev/followers","following_url":"https://api.github.com/users/emanuil-tolev/following{/other_user}","gists_url":"https://api.github.com/users/emanuil-tolev/gists{/gist_id}","starred_url":"https://api.github.com/users/emanuil-tolev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/emanuil-tolev/subscriptions","organizations_url":"https://api.github.com/users/emanuil-tolev/orgs","repos_url":"https://api.github.com/users/emanuil-tolev/repos","events_url":"https://api.github.com/users/emanuil-tolev/events{/privacy}","received_events_url":"https://api.github.com/users/emanuil-tolev/received_events","type":"User","site_admin":false},"created_at":"2015-07-17T16:56:26Z","updated_at":"2015-07-17T16:56:26Z","body":"Another big note to make is that I've decided to leave the API docs public - including for the private routes. I was about to hack flask-swagger to let us have one public docs page with 2 routes and one private docs page for publishers with all the rest of the routes, but actually this is not usual. I would recommend leaving the docs open and fielding the occasional question \"how do I use this route\", \"how do I get an API key\" - I think it's important to expose what the DOAJ *can* do and be aware of what people might want to do with it.\r\n\r\nIf we keep the docs for the authenticated APIs private we'll never know what people might want to do with it. It may well be that DOAJ decides to create a publisher account for a particularly enthusiastic researcher, OA advocate, or developer from a non-publisher organisation like a repository manager and let them submit data to DOAJ. Additionally there may be considerable interest in the applications that DOAJ fields from the public.\r\n\r\n@dommitchell I'd love to hear your thoughts on this (and everybody else of course). It is possible to keep the authenticated API pages private as well, though a bit more difficult. The usual case is that the documentation for an entire API is published, and then you may or may not have a key and may or may not have rights to do certain things (but can still read related docs)."}}