florianmartens

Nice. This is interesting and maybe I can connect this with pipe0.com to add emails, phone numbers, etc.

The value of clay is is not its code base IMO. Clay connects many providers that each have licenses starting around $100-150/mo. Even if you open source your solution, users would still have to purchase subscriptions individually, manage their usage, etc. This can get expensive quickly. On top, it takes time and is annoying. Lastly, there's complexity to self-hosting the AI and web scraping stuff. I'm unsure if there are many GTM teams willing to put up with hosting this themselves.

Fun fact, you can actually rebuild the entire core functionality of clay using https://pipe0.com with ~1000 lines of code.

Thanks for posting this. I'm building https://api-fiddle.com and need to have this on the map as a potential default format for the editor.

Try api-fiddle.com as a replacement for stoplight.io :)

I've bookmarked your blog and will follow along to see what kind of solution you come up with in the end :)

Yeah, I think even if you are fairly technical it's still pretty hard to manage a growing OpenAPI doc that is good enough to generate clients, sdks and docs from it.

I think that we'll soon be able to help you generate mock clients as well. Probably by generating a first pass with AI and letting you adjust the details manually. This way it could be one-click.

That's really cool. We're on a similar path with https://api-fiddle.com

We're trying to build the best tool out there for team that want to build api-first and speed up development and code generation this way.

I'm happy you wrote this article!

Here are a few questions for you: - Do you think the mock API is the best way to get Feedback from stakeholders? - How do you merge your changed OpenAPI document into your master documentation when it's time for prod? - How do you share your draft contract with e.g. a frontend engineer so they can get started building the UI?

I think this is a good intro into OpenAPI contracts. What generally sells people into OpenAPI is:

1.) The ability to document things with tools like swagger ui, api-fiddle, scalar 2.) The ability to automate things with auto-generated api-clients, mocks, tests 3.) The ability to secure things with tools like Cloudflare API Shield 3.) The ability to go api-first and speed development up

I agree. API-first is the way! Change your schema, auto-generate types into your code and use them for your server definition. It's just faster and more secure this way. Use api-fiddle.com or spotlight.io to work with the schemas (branching, sync with Github).

In a fully typesafe world, it should be pretty hard to derive from the shema this way.

This article is awesome and resonates with my experience! I used to work for one of the big cloud vendors. We frequently had doc writers in our sync calls. Quite frankly, they never had a chance! Much of our documentation, our errors, status codes etc. was burried in the code and we (developers) were simply to busy to work effectively with technical writers.

Don't get me wrong here. Where I say "busy" I don't mean their work wasn't important (it was!) but we had our own projects and jumping on a call to improve errors messages is not too exciting for most of us - and it's not the stuff that drives promotions. As a develper it's simply to easy to gatekeep code.

Now follows a shameless plug: I'd be so excited to hear your opinion about a tool I'm building. It's called https://api-fiddle.com. Conceptually, it should help developers work API-first instead of code-first. It's great for devs because it makes the work faster and safer. BUT, an added benefit is that API docs are no longer burried in code and technical writers have a nice interface to contribute to them (and hold devs accountable!).

Dieter Rams’ design philosophy encourages simplicity, honesty, and functionality—values that translate beautifully into the world of API design. By applying these 10 principles to REST APIs, developers can create APIs that are not only functional and efficient but also enjoyable and intuitive to work with.

Hopefully the last blog post you ever have to read on the matter

I'd definitely declutter the index page. It's literally too (ooo...) much text. Maybe clarify your value proposition.

Hm, I'd also argue that accountability would help. Create it somehow find a partner with whom you work out. Document you workout in a blog, youtube, whatsapp conversation, conversation on Eightygram.

Or, ignoring technology. Find a personal trainer. Or a really small workout group that has some sort of trainer that really cares.