How do you manage changes to your API?

[acunniffe]

We believe stories are the most valuable thing users can share. If you're willing to take a few minutes to share some of yours, we'd really appreciate it. You'd be surprised how influential these stories can be when we make decisions about what to build next.

Usually we do this over the phone, but hey, we'll try a public ledger and see how it goes :)

Copy these questions into your answer:

Our current process for documenting our APIs + Reviewing API Changes

What about this process works well?

What about this process has not worked well? Do you have an example (that's ok to share) of an issue this caused?

That way I wish things worked was....
be bold, reimagine anything and everything

What do you like about Optic? What's the most important thing about the project? What would you do differently?

[dyc3]

Project: https://github.com/dyc3/opentogethertube
(I might edit this post later)

Our current process for documenting our APIs + Reviewing API Changes
Non-existent. I was only just starting to document our api when I found optic.

What about this process works well?
Getting a bare minimum setup that works is very painless.

What about this process has not worked well? Do you have an example (that's ok to share) of an issue this caused?
Currently, I have yet to figure out the optimal solution for integrating optic into my workflow. If I set up optic when I first started my project, I probably wouldn't have this problem.

The way my project works is I have the vue web server on 8080, and the API on 3000 using nodemon, and the vue web server proxies all requests on the base path /api to the api server. Both servers get run at the same time when you run npm run dev using concurrently. I could run optic in proxy mode or set it up so that api start starts the server but its not entirely clear what would be best for my setup, or what layer in this proxy clusterfuck I should place optic. More importantly though, I'm worried that integrating optic to my project will make it harder for new contributors to set up the project locally.

---

I started documenting my API manually here: https://github.com/dyc3/opentogethertube/blob/master/docs/api.yaml

As you can see, I didn't really get too far, but I've already documented some schemas at the bottom, and some metadata at the top about the API. I want to be able to detect when those schemas are inconsistent, or enforce consistency across multiple responses. I wish optic could import this information, and then output clean changes to the document when something changes. In other words, I wish it could just modify my existing spec instead of assuming that I don't have one.

That way I wish things worked was....

• I wish that the command was called optic and not api, because it makes it more obvious what software package is supplying that command. To people that are not familiar with optic, the api command could be literally anything.
• I wish I could just stick optic in my devDependencies and just assume that it'll get installed when people do npm install

What do you like about Optic? What's the most important thing about the project? What would you do differently?
I like the guided setup, and the workflow that optic enables. I'm not sure what I would do differently.

[acunniffe]

Thanks, @dyc3 -- we appreciate the time you spent sharing feedback here.

Overall -- I think you bring up a lot of good points about fitting Optic into the developer workflow. I like how conscious you are of how your contributors will be affected by the integration path you choose for Optic. I'm sure they appreciate that you're thinking about them.

I wish it could just modify my existing spec instead of assuming that I don't have one.

You're definitely not alone here. Today we think about Optic as a way to make sure API changes in code get detected, reviewed, and documented. We've been experimenting with a design-first inspired mode as well where you start with a spec you provide/maintain. By default, Optic is making sure your API is consistent and meeting its contract. In this mode the default is to guide you towards updating your code to meet the API, not updating your spec to meet the real behavior of your code. API evolution and change management are complex and we think, depending on the day's work, you might find yourself wanting each mode for different jobs. We blogged about what's coming here

I wish that the command was called optic and not api, because it makes it more obvious what software package is supplying that command. To people that are not familiar with optic, the api command could be literally anything.

This is good feedback, we've heard similar asks from a few others. Trying to be too invisible can hamper learnability

I wish I could just stick optic in my devDependencies and just assume that it'll get installed when people do npm install

I think you could actually do this with a node project since Optic can be installed via npm. You might change this to:

"api-server": "nodemon --inspect app.js",
"api-server": "npx api start",

---

You've hit on two of my big goals:

1. Learn about issues and improve how Optic fits into existing projects
2. Learn about and improve Optic's fit into the workflows/jobs users want it to handle for them

^ I'll definitely be asking for feedback on some upcoming changes. Thanks for everything

[dyc3]

"api-server": "npx api start",

Would that still let me attach a debugger, and auto restart the api server when the files change?

[LouManglass]

To keep @acunniffe in the loop: @dyc3 and I are working on a sample integration of OpenTogetherTube with Optic, I've put a first step together with notes. We're going through practical questions and demonstrating that Optic can work and provide the ability to auto-restart api-server on changes and run a debugger. We're still working to assure it's smooth and doesn't get in the way of contributors.