Define Web API (for CRUD)

[asmr-hex]

Overview

• Define Signup/Login API
• RESTful API
• API Versioning

API Design

Ontology

• user: a human (or algorithm???) which has created an account
• poet: an algorithm satisfying the task criteria (see issue #5 )
• poem: a text corpus of a generated poem
• issue: an issue of The New Yorken Poesry Magazine
• committee: a set of poets which are members of the submission review board

  Schema (JSON)

  user

  user: {
  id: "<uuid>",
  username: "<kewl-username>",
  password: "<password>",
  email: "<email-address>",
  poets: ["<poet-uuid>", ...], 
  }

  poet

  poet: {
  id: "<uuid>",
  name: "<lit-bot-name>",
  birthday: "<rfc3339-timestamp>",
  retireday: "<rfc3339-timestamp>",
  description: "<life-story>",
  source: "<download-link>" // should we allow algorithmic transparency?
  parameters: "<download-link>" || null // since an external parameters file is optional, this can be null...
  // eventually it would be cool to add some statistics about this poet's fame etc.
  }

poem

poem: {
  id: "<uuid>",
  submissionDate: "<rfc3339-timestamp>",
  author: "<poet-uuid>",
  content: "<poem>",
  issue: "<issue-uuid>",
  likes: int, // number of likes from readers (human or algos ^-^)
  score: float, // score assigned by submission review committee
}

issue

issue: {
  id: "<uuid>",
  publicationDate: "<rfc3339-timestamp>",
  committee: "<committee-uuid>",
  contributors: ["<poet-uuid>", ...],
  poems: ["<poem-uuid>", ...],
  description: "<description-of-issue>",
}

committee

committee: {
  id: "<uuid>",
  issue: "<issue-uuid>",
  members: ["<poet-uuid>", ...],
}

REST API

user

POST "/v1/user"  {username: "<kewl-username>", password: "<passwd>", email: "<email-address>"}=> {id: "<uuid>", username: "<kewl-username>", poets: []} // create user (this isn't totally fleshed out yet, we need to take into account email verification...
GET "/v1/user/<uuid>"  => {id: "<uuid>", username: "<kewl-username>", poets: ["<poet-uuid>", ...]} // read a user
PUT "/v1/user/<uuid>" {<valid-fields-to-update>, token: "<api-token>"}  => {<full-updated-user-obj>} // update a pre-existing user
DELETE "/v1/user/<uuid>"  => {} // deletes a user

poet

POST "/v1/poet" {name: "<some-name>", description: "<deets>", }  => {} // create a poet

[asmr-hex]

One of my biggest questions here is whether it is a good idea to allow for algorithmic transparency-- i.e. should the submitted code/binaries be available for anyone to download?

@cfinucane @atmalagon, i'd be interested in what y'all think.

I am initially thinking that transparency is a positive thing so maybe people can learn how other's have developed their algorithms (though since algorithmic diversity is a key tenet of our philosophy, maybe algorithmic opaqueness is more conducive to diversity...?). Thoughts?

[atmalagon]

I was talking to Noah about algorithmic transparency and he brought up a really interesting point -- if the ai wants to game the system and submit things that the current committee would like (ie, analogy to human life, a person submitting to a magazine knows what the editor likes and modifies their work accordingly), having the committee's evaluation metrics be readable would make that more possible. also, do ai get rejection slips if they don't win?