[API][WIP] Expected JSON Spec for `Projects` Endpoint

[BethanyG]

Current thinking on the JSON Spec for the Projects api endpoint. Opening this as a separate issue from fixtures, as we need to discuss the fields, data types, relations, and formats needed to implement a model for the DB. Current proposed fields and POST format below:

{    "fields":{
              "title":"webpack",
              "creator":"Tobias Koppers",
              "description":"open-source JavaScript module bundler",
              "url":"https://github.com/webpack/webpack",
              "user":8,
              "date_published":"2019-09-19T04:29:04Z",
              "created":"2019-09-19T04:29:04.069Z",
              "modified":"2019-09-19T04:29:04Z",
              "open_to_contributors":true,
              "contributors": [1, 9, 3, 8, 23, 19, 23] 
                }
 }

---

Open Questions/Comments

1. Omitted the guid listed in the fixtures spec as it will be generated randomly by the ORM code on DB insert of the POST.

2. Are contributors CB members that are known to contribute to the project? If so, suggest the field be renamed contributing cb members or something similar for clarity.

3. Are contributors intended to be FK links to the users_user table?

4. Will we be tagging projects in a similar fashion to the way we've tagged resources, should we be adding a tags field??

5. Will the JSON returned from a GET look any different from this POST JSON? If so, what would the GET returned JSON look like? Some things to think about:

   • If we do include tags, will we want them displayed in the same fashion as resources e.g. POSTed as a list, GET as a list of name:slug pairs?
   • Will we want to expand the ccontributors UID list on GET to be the usernames of the users referenced?
   • Will we want to expand the user on GET to return the username of the "owner" of the project listing??

[BethanyG]

Proposed changes below:

{    "fields":{
              "title":"webpack",
              "project_creator":"Tobias Koppers",
              "description":"open-source JavaScript module bundler",
              "url":"https://github.com/webpack/webpack",
              "user":8,
              "date_published":"2019-09-19T04:29:04Z",
              "created":"2019-09-19T04:29:04.069Z",
              "modified":"2019-09-19T04:29:04Z",
              "open_to_contributors":true,
              "contributing_cb_members": [1, 9, 3, 8, 23, 19, 23],
              "tags": ["bundlers", "front end", "java script", "js", "tools"]
                }
 }

[billglover]

@BethanyG, @lpa I'm struggling to comment on the JSON structure as I'm unsure what role a Project plays. Do we have a link to a higher level use case or problem statement that I can use to give me a frame of reference?

Thoughts I'm hoping to understand with a greater understanding of the use case:

• Why do we appear to be tracking contributors to an external Git project?
• If a project is managed on GitHub, why are we tracking it on CB?
• How do keep the "open for contributors" field up to date and avoid it becoming stale as external projects change their status.
• What is the difference between a user and a project_creator?

[lpatmo]

Great questions! @BethanyG actually asked similar ones, IIRC. :)

Why do we appear to be tracking contributors to an external Git project? Was thinking that the maintainers of open source projects could create projects on the CB site, and invite CB members who might want to "join" the project as a member in the sense of following along on what's happening with the project.

Analogy: open source maintainers creating a Slack channel for their project on the CB Slack. Alternatively: #codebuddies-meta, except discussions would be on the project page on the CB site.

If a project is managed on GitHub, why are we tracking it on CB? One of the initiatives we identified from https://pad.riseup.net/p/BecKdThFsevRmmG_tqFa-keep was to better connect open source maintainers with potential contributors, so this project page would be a way for project creators to showcase their projects with the rest of the community.

How do keep the "open for contributors" field up to date and avoid it becoming stale as external projects change their status. GREAT question. Short answer: maybe we can't, if maintainers don't use their project page actively. :( This is a potential real problem.

What is the difference between a user and a project_creator? The user is the CB user ID that created the project; the project_creator could be the GitHub handle of the original creator or maintainer of the project.

Side note: @bkbuilt and I discussed briefly requesting a bunch of meta data from GitHub about each project based on the project URL.

---

Also, apologies for not presenting UIs or making any of the "why" behind this API design clear -- I mainly was looking to find something small @bkbuilt could start working on that wasn't resources, and it snowballed into discovering together that defining the process for creating new API endpoints in general would be helpful.

I feel like I've been too busy to make necessary mock-ups and design decisions on the front-end, and will try to focus on that more in the coming week after I'm back from Vancouver.

[billglover]

No apologies needed at all. I think this is exactly the type of discussion we should be having about endpoints. I'm wondering if we could pair this back a little and ship a cut down version of the idea. This would allow us to add to it as we see how it is used. Removing features (aka fields) is much harder than adding them.

Could we start by using the Projects endpoint to track projects that the CB community have identified as being great starter projects? We could build this, ship it and then add features as needed.

{
  "title":"webpack",
  "creator":"Tobias Koppers",
  "description":"open-source JavaScript module bundler",
  "url":"https://github.com/webpack/webpack",
  "cb_user_id":"4226b3e2-7b8c-4794-973f-33d57e3823a1",
  "created":"2019-09-19T04:29:04.069Z",
  "modified":"2019-09-19T04:29:04Z"
}

• title - a read-only field, fetched from the project URL
• creator - could be fetched from project or free text
• description - a read-only field, fetched from the project URL
• url - validated on entry (start with GitHub only)
• cb_user_id - a read-only field, set as the GUID of the user who created the entry
• created - a read-only field, set on POST
• modified - a read-only field, set on PUT/POST

Things like members, tracking, and discussion can be added later without breaking the API contract. We may want to add tagging ourselves, but could pull in things like languages from the GitHub project URL.

[BethanyG]

I like the idea of pulling in initial tags information from the languages identified in GitHub - would there be a way to do this on the front-end, to "pre-populate" the tags field? That way, users could add additional tags if needed..but we'd have an automatic "baseline", so we could do filtering/searching.

[BethanyG]

Closing this as no longer relevant for current development.