Page MenuHomePhabricator
Create Task
Maniphest T119271

Write swagger spec for ORES
Closed, ResolvedPublic
Actions

Description

Write a swagger spec for ORES and expose it via the service. See http://editor.swagger.io/#/ and https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

swagger: '2.0'
info:
  title: Objective Revision Evaluation Service
  description: Provides access to scoring models for MediaWiki revisions
  version: 0.7.2
host: ores.wmflabs.org
schemes:
  - http
  - https
basePath: /v1
produces:
  - text/html
  - application/json
paths:
  /scores:
    get:
      summary: Score revisions
      description: ...

Related Objects
Search...

StatusSubtypeAssignedTask
 ResolvedNoneT122271 [Epic] ORES 1.0.0
 ResolvedHalfakT119271 Write swagger spec for ORES

Event Timeline

Halfak created this task.Nov 21 2015, 12:37 AM
Halfak claimed this task.
Halfak raised the priority of this task from to Needs Triage.
Halfak updated the task description. (Show Details)
Halfak added a project: Machine-Learning-Team (Active Tasks).
Halfak moved this task to Parked on the Machine-Learning-Team (Active Tasks) board.
Halfak subscribed.
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald TranscriptNov 21 2015, 12:37 AM
Halfak updated the task description. (Show Details)Nov 21 2015, 12:37 AM
Halfak set Security to None.
Halfak added a subscriber: • GWicke.Nov 21 2015, 12:56 AM

It seems like @GWicke's been following the convention of <service base>/?spec to get the specification. We should do that too.

Halfak added a comment.Nov 21 2015, 1:13 AM

Note that this spec include some installation details (e.g. "host" and "scheme"), so we'll need to make those merge-able from installation specific configuration.

Halfak mentioned this in T107196: Set up revscoring entry points in RESTBase.Nov 21 2015, 1:16 AM
Ricordisamoa subscribed.Nov 21 2015, 3:44 AM
• DarTar subscribed.Nov 21 2015, 4:37 AM
Halfak mentioned this in T107723: Extend the GUI for ORES.Dec 4 2015, 8:26 PM
Halfak added a comment.Dec 10 2015, 1:26 AM

See some notes and discussion about including fitness metrics and plots in the spec. https://meta.wikimedia.org/wiki/Talk:Objective_Revision_Evaluation_Service#Automatically_generated_documentation

Halfak added a comment.Dec 10 2015, 1:29 AM

Oh! Also, I had some thoughts about how to deal with the differing routes when accessing ORES directly vs. through the wikimedia paths (e.g. en.wikipedia.org/api/ores/...)

So we'll probably want a spec to be available at "/?spec" that will describe the whole system. We can also have a different spec at "/<wiki>/?spec" that will report routes that are specific to that particular wiki. This sub-spec can be linked to directly from "en.wikipedia.org/api/".

Halfak added a project: ORES.Dec 23 2015, 4:23 AM
Halfak added a parent task: T122271: [Epic] ORES 1.0.0.
Ladsgroup subscribed.Feb 23 2016, 9:10 PM

Another note: Let's wait until api v2 is merged (https://github.com/wiki-ai/ores/pull/121) then write the swagger :)

Ladsgroup moved this task from Parked to Backlog on the Machine-Learning-Team (Active Tasks) board.Feb 23 2016, 9:10 PM
Halfak added a comment.Feb 24 2016, 12:11 AM

We could use the swagger spec to design v2 ;)

Halfak moved this task from Backlog to Paused on the Machine-Learning-Team (Active Tasks) board.Mar 5 2016, 4:36 PM
Ladsgroup added a comment.Mar 12 2016, 3:36 PM

Started: https://etherpad.wikimedia.org/p/ores_swagger

Halfak added a comment.Mar 13 2016, 5:58 PM

I took a pass on this. It looks like many of the endpoints were left undocumented and much of the documentation was copied from some example. I filled in a bit, but it will need more work.

Ladsgroup moved this task from Paused to Backlog on the Machine-Learning-Team (Active Tasks) board.Mar 13 2016, 9:58 PM

Yeah, I just started it, it definitely needs more work. Thank you for making it better. I'll work on it tomorrow

Halfak added a comment.Mar 16 2016, 3:02 PM

I think we'll need different specs for v1 and v2 paths.

E.g. https://ores.wmflabs.org/v1/?spec should return the API spec for v1 and https://ores.wmflabs.org/v2/?spec should return the spec for v2.

Ladsgroup added a comment.Mar 16 2016, 9:27 PM
In T119271#2126229, @Halfak wrote:

I think we'll need different specs for v1 and v2 paths.

E.g. https://ores.wmflabs.org/v1/?spec should return the API spec for v1 and https://ores.wmflabs.org/v2/?spec should return the spec for v2.

+1

Halfak added a comment.Mar 20 2016, 10:40 PM

See https://github.com/wiki-ai/ores/pull/131

Halfak moved this task from Backlog to Completed on the Machine-Learning-Team (Active Tasks) board.Mar 20 2016, 10:40 PM
Halfak moved this task from Completed to Review on the Machine-Learning-Team (Active Tasks) board.
Ladsgroup moved this task from Review to Completed on the Machine-Learning-Team (Active Tasks) board.Mar 20 2016, 11:43 PM
Halfak closed this task as Resolved.Mar 21 2016, 3:54 PM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits