Design Project API

[cadecairos]

• Create a project
  • POST /projects
• Update project
  • PATCH /projects/{id}
• Delete a project
  • DELETE /projects/{id}
• Get project data
  • GET /projects/{id}
• Get remixes of a project
  • GET /projects/{id}/remixes
• Create a remix of a project
  • POST /projects/{id}/remixes

[xmatthewx]

Can we make it possible to remix a single page within a project? The goal: lower the bar for participation and increase activity on the platform.

[cadecairos]

Can we make it possible to remix a single page within a project? The goal: lower the bar for participation and increase activity on the platform.

see #7

[cadecairos]

Also,

• List Projects
  • GET /projects
  • query parameters for sorting, pagination, optional flag to also retrieve page data for projects?

[xmatthewx]

see #7

:boom:

[thisandagain]

I suggest we make /projects a sub-resource of /users/:user as it makes cache invalidation quite a bit easier and also properly reflects the ownership of the resource ala: /users/:user/projects.

[thisandagain]

I don't see anything in the designs that require sorting or retrieval of page data that would prohibit another HTTP request. Pagination seems like a requirement anywhere where the API is returning an array.

[davidascher]

We need localized searches, no? "Show recent/featured projects for this locale?" "show recent/featured projects near this latlong?"

[thisandagain]

We don't have any features / UX for geolocation yet, just locale at this point.

[cadecairos]

@thisandagain we could have /users/:user/projects and also have /projects which defaults to listing either the authenticated user's projects, or the default list of public project data.

[thisandagain]

@cadecairos That's true ... I like the idea of having /projects be a raw feed of all public projects. Having /projects list only the authenticated user's projects seems awfully non-restful and difficult to cache.

[thisandagain]

Here is a crack at another sketch:

API

GET /projects – List of all projects (both featured and not featured)

GET /users/:user/projects – List of all projects from the specified user
POST /users/:user/projects – Create a new project
GET /users/:user/projects/:project – Get an existing project by ID
PUT /users/:user/projects/:project – Update an existing project by ID (auth, owner)
DEL /users/:user/projects/:project – Delete an existing project by ID (auth, owner)

GET /users/:user/projects/:project/remixes – Get all remixes of an existing project by ID
POST /users/:user/projects/:project/remixes – Create a new remix of an existing project by ID
^ this last resource seems weird / wrong

Data Model

{
    "id": 1,
    "version": "1.0.2",
    "title": "Yam Fries 4000",
    "featured": true,
    "history": {
        "created_at": "2015-04-20T16:11:13.961Z",
        "updated_at": "2015-04-20T16:11:13.961Z",
        "deleted_at": null,
    },
    "thumbnail": {
        "400": "https://blah.storage.com/some/image.jpg",
        "1024": "https://blah.storage.com/some/image.jpg"
    }
}

[cadecairos]

POST /users/:user/projects/:project/remixes – Create a new remix of an existing project by ID ^ this last resource seems weird / wrong

the basis for that was https://developer.github.com/v3/repos/forks/#create-a-fork

[thisandagain]

Cool. Works for me! Thanks for the reference.