create an API of common developer terms

[clandau]

Issue Context

As discussed in Slack, it would be great to create an API of common developer terms, and a browser extension and/or page in virtualcoffee.io. When a learner comes up on a term they don't understand, they can use the resource to easily find the definition and helpful resources/examples.

Suggested Solution

We would build an API of common developer terms, which would include the definitions and other resources like example. This would then be used to build a browser extension and/or page on virtualcoffee.io.

I feel that we should focus on the API first, with this issue, as we'll need a functional API to build the other two projects. We could start issues for those projects when we have the API to work with. This is open for discussion.

Alternatives Considered

Additional Resources

[clandau]

Does anyone have any suggestions on how we compile the terms/definitions?

[danieltott]

One option could be to store them in JSON and have 11ty and/or netlify functions serve them up in various ways.

Maybe a good thing to figure out is how we want the API to behave - what are the requirements for the API? Is the API read-only, and managed somewhere else?

[clandau]

i'm thinking something like give it a term with a GET and get a definition, and supplemental resources/links. It might be good to be able to POST definitions through the API too, but that would need to be protected or verified somehow to avoid inaccurate posts.

[Rahat-ch]

I think being able to POST would definetely be a good thing to have. I was sort of invisioning something like this:

A form that can be filled out that makes a POST request with the supplied info. We could have an "approved" flag that defaults to false and maybe a seperate UI with a list of unapproved stuff to look through as they come in.

Let me know if this is too out there 😅

[danieltott]

@Rahat-ch Definitely not too far out there!!

You've both hit on my concern for having a POST available for any API - we'd need to add moderation stuff, and we'd most likely want to add some sort of auth in front of it to prevent abuse. Not saying it's not doable obviously - but if it's possible to have the MVP only have read access, and manage the data elsewhere, it could simplify things for the first round. The data could be managed via pull requests even if we're storing via json, or in a database somewhere.

I do think a "request x to be added" form is a great idea and could be worked to fit really any model.

Some things to decide regardless:

Backend

An API is an interface for a third party to access some app or service. So - what do we want this to look like? How are we storing/changing data? There are infinite options, really, all with pros and cons.

• Flat JSON (stored here or somewhere else)
• Markdown + head matter (stored here or somewhere else)
• Cloud database service (Firebase et al)
• Some other live database

If we went with some sort file-based storage (JSON or Markdown), then our API tech can handle any of the read-related operations however it wants, and we already have the services in place to handle them (github + netlify for hosting). However, mutation via API gets much harder.

I will be adding netlify CMS to the VC site at some point - that might be an option for this as well but I'm not going to force it if it doesn't fit right with everyone else. Netlify CMS saves data as Markdown + head matter and could definitely work for something like this.

I would be very glad to elaborate more on my ideas here if anyone wants.

Once we move to other third-party services, we'll have to figure out pricing and access - absolutely not ruling any of it out, there's just a lot to consider on that end. We don't have anything set up in this realm currently.

However, some of the other bits become a bit easier here. Setting up roles and mutation access are ready out of the box most likely.

API behavior

How does the API access the backend and display the info

This answer does not have to depend on the backend decisions above.

If we use firebase or another cloud db, I think we'd want to wrap that with something we control, so that people consuming the API aren't connecting directly to firebase. we can do this via netlify functions, or use any number of backend languages to proxy the cloud API and host on heroku or digital ocean or something like that.

If we are using a file-based backend, especially if it's on netlify, we can serve data directly from netlify via either pre-built paths or netlify functions (or a combination probably).

Access

• Are read routes protected at all
• If there are mutation routes, what sort of protection

Actual endpoints and behavior

REST vs GraphQL? or both?

Read:

• List
  • Filtering (search etc)
  • Sorting
• Detail

Mutate:

• Create
• Edit
• Delete

Other thoughts

I would think this should be just the first endpoint for the Virtual Coffee API. That doesn't mean that we need to solve every conceivable problem ahead of time, but it will drive some of my thinking as far as things like "where is this API located on the web" and I would love to hear all of your thoughts on that as well. api.virtualcoffee.io? virtualcoffee.io/api?

I know I keep mentioning netlify/static files/11ty etc. There are good reasons, but also I'm very susceptible to the "when you have a good hammer everything looks like a nail" thing, so please take what I'm saying here as thoughts or brainstorming, and not me saying "I have spoken" and taking all the wind out of this project. That being said I think we could do some really cool things with this.

Please keep up the energy and the brainstorming!

[vintprox]

• Markdown + head matter (stored here or somewhere else)

Markdown with frontmatter? Makes sense to me! Here are some advantages of Markdown notes...

• Availability

  Anyone can open these files anywhere and interpret contents straight away.

• Distribution

  Update notes locally when needed, retaining original version and reviewing changes with Git/GitHub if any.

• Simplicity

  Format is suggesting lesser confusion for any willing contributors, and we may have very straightforward syntax for each note to accomodate this philosophy.

• Interoperability

  Some contributors can organize these notes with Foam, while others can simply contribute via GitHub web version or github.dev.

  I may be opinionated here, but solution that does NOT curate updated field in the frontmatter is more consistent with version control, unlike what Dendron does.

  API that parses such pure structure is a bliss for maintenance.