Page MenuHomePhabricator

Write swagger spec for ORES
Closed, ResolvedPublic

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: ...

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 moved this task to Active on the Scoring-platform-team (Current) board.
Halfak added a subscriber: Halfak.
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.

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

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.

DarTar added a subscriber: DarTar.Nov 21 2015, 4:37 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

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 parent task: T122271: [Epic] ORES 1.0.0.

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

We could use the swagger spec to design v2 ;)

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.

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

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.

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 moved this task from Done to Review on the Scoring-platform-team (Current) board.
Halfak closed this task as Resolved.Mar 21 2016, 3:54 PM