[w3news]

When you build an API, please start with the OpenAPI specification, before you write any code for your API. It can be iterative, but for every part, just start with the OpenAPI, and think about what you want from the API, what do you want to send, and what to receive.

It is like the TDD approach, design before build.

Writing or generating tests after you build the code, is the same as this. It is guessing what it should do. The OpenAPI specification, and the tests should tell you what it should do, not the code.

If you have the specification, everyone (and also AI) can write the code for you to make it work. But the specification is about what you think it should do. That are the questions and requirements that you have about the system.

[brosciencecode]

I get the feeling you may not have gone 0-1 on an API before. In general, you have 1 consumer when you're starting off, and if you're lucky your API gathers more consumers over time.

In that initial implementation period, it's more time-consuming to have to update a spec nobody uses. Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory.

I'd instead ask: support and use API frameworks that allow you to automatically generate OpenAPI specs, or make a lot of noise to get frameworks that don't support generating specs to support that feature. Don't try to maintain OpenAPI specs without automation :)

[Karrot_Kream]

How is adding 10-20 lines, depending on how many structures you're creating, and then re-running a generation tool (or simply just running a build command again depending on your build configuration) time consuming? I've written OpenAPI-first services both at Big Tech for services handling crazy amounts of RPS and at tiny seed startups where we release the API and literally nobody uses it but our app. Sure I've run up against the occasional sharp edge/incompatibility with some form of nested structure and the generator we used but it was usually a minor diversion and represented 20-30 min of wasted time for the occasional badly-behaving endpoint.

I'm even writing a side project now where I'm defining the API using OpenAPI and then running a generator for the echo Go framework to generate the actual API endpoints. It takes just a few minutes to create a new API.

[rad_gruchalski]

I don’t agree with you. Write a spec, use generators to generate your servers and clients, and use those generated objects yourself.

The point is twofold: you test your API immediately AND you get a ton of boilerplate generated.

So many products out there just feel like a bunch of separate things with a spec slapped on top. Sometimes the spec doesn’t make sense. For example, the same property across different endpoints having a different type.

Save yourself time and do it right from the get go.

> Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory.

So yeah, write your spec once and generate all servers and clients from it…

[tevon]

I agree with this as well!

OpenAPI spec seems intended to be consumed, not written. Its a great way to convey what your API does, but is pretty awful to write from scratch.

I do wish there was a simpler language to write in... JSON-based as well that would allow this approach of writing the spec first. But alas, there is not, and I have looked a loooot. If anyone has suggestions for other spec languages I'd love to learn!

[devbit]

OpenAPI specs can save weeks even on small projects, when you need to autogenerate multiple clients in different languages after the API part is ready btw

[paholg]

I don't want to write OpenApi. Yaml is a terrible programming language, and keeping it in sync with actual code is always a nightmare.

I've been using a tool to generate OpenApi from code, and am pretty happy with that workflow. Even if writing the API before logic, I'd much rather write the types and endpoints in a real programming language, and just have a `todo` in the body.

You can still write API-driven code without literally writing OpenApi first.

[rad_gruchalski]

You can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.

[BerislavLopac]

You are correct about YAML, but OpenAPI is not YAML -- it just commonly uses it as for the textual representation. As others mentioned it, JSON is an alternative, although it doesn't make it much easier to write the code directly.

Sadly, there is a distinct lack of tools to make spec-first development easier. At the moment, Stoplight [0] is the only game in town as a high quality schema editor, but it requires payment for any more significant usage.

[0] https://stoplight.io/

[rnts08]

Absolutely, and yes YAML is trash.

[adawg4]

Which tool?

[Rabidgremlin]

100% agree with you... taking the time to do/go design first greatly improves the quality of the final API...

But as some comments below point out, an OpenAPI spec is a pain to create manually which is why TypeSpec from Microsoft is such a great tool. Lets you focus on the important bits of creating a solid API (model, consistency, best practices) in an easy to use DSL that spits out a fully documented OpenAPI spec to build against! see https://typespec.io/

[tkiolp4]

What’s wrong with designing an API by writing its code? Code itself is a design tool (and usually any decent programming language is a better design tool than YAML)

[spondylosaurus]

As someone who documents APIs: it's easy to tell which APIs were designed with intention and which ones were designed on the fly. In part because it's much, much easier to document the former :)

[madeofpalk]

Unfortunately OpenAPI specs suck to write manually.

Generating OpenAPI spec from the server code has always felt significantly better for me.

[yashap]

I completely agree as a general design principle, but I still think there’s a place for the above tool.

Example: I used to work at a place that had a massive PHP monolith, developed by hundreds of devs over the course of a decade, and it was the worst pile of hacky spaghetti code I’ve ever seen. Unsurprisingly, it had no API spec. We were later doing tonnes of work to clean it up, which included plans to add an API spec, and switch to a spec-first design process (which we were already doing in services split from the monolith), but there was a massive existing surface area to spec out first. A tool like this would’ve been useful to get a first draft of the API spec up and running quickly for this huge legacy backend.

[enobrev]

The API library I wrote for my last couple projects required the developer to fill in the openapi spec specifics and said spec was the part of the API itself, making it difficult to add something to the API that wasn't also in the spec.

Incoming request params, became validated and casted object properties. Outgoing response params were validated and casted according to spec.

In the end I think it worked really well, and loved not needing to maintain the spec separately. The annoying bit was adjusting the library when the spec changed.

And some gnarly bits of the spec that weren't easy to implement logically.

At any rate, it also made for a similar experience of considering the client experience while writing/maintaining the api.

[physicsguy]

I prefer going the other direction in practice, autogenerating the spec from the code e.g. with drf-spectacular for Django.

[pattycakes]

Waste of time imo if you use a framework like fastapi which generates the spec for you

[ramraj07]

Exactly this, I’ve been a python guy which is apparently not the main language used by most api developers or what? Is there nothing like FastAPI in js land? I do start my APIs by writing the openAPI spec, only it’s written in pydantic inside FastAPI and turns out this also creates the actual API lol.

[mdasen]

As a curiosity, how do you feel about languages/frameworks where APIs can be pretty self-documenting? For example, Java/JAX-RS creates pretty self-documenting APIs:

    @Path("/people")
    public class PeopleApi {
        @Path("{personId}")
        @GET
        public Person getPerson(@PathParam("personId") int personId) {
            return db.getPerson(personId);
        }
    }

It's easy to generate a spec for a JAX-RS class because it has the paths, parameters, types, etc. right there. There's a GET at /people/{personId} which returns a Person and takes a path parameter personId which is an integer.

If we're talking about a Go handler which doesn't have that information easily accessible, I understand wanting to start with a spec:

    func GetPerson(w http.ResponseWriter, r *http.Request) {
        personId, _ := strconv.Atoi(r.URL.Path.something)
        person := db.GetPerson(personId)
        w.Write(json.marshal(person))
    }

    func GetPerson(c echo.Context) error { //or with something like Echo/Gin
        id := c.Param("id")
        person := db.GetPerson(id)
        return c.Json(http.StatusOK, person)
    }

In Go's case, there's nothing which can tell me what the method takes as input without being able to reason about the whole method. With JAX-RS, it's easy reflect on the method signature and see what it takes as input and what it gives back, but that's not available with Go (with the Go tools that most people are using).

This isn't meant as a Go/Java debate, but more a question of whether some languages/frameworks basically already give you the spec you need to the point where you can easily generate an OpenAPI spec from the method definition. Part of that is that the language has types and part of it is the way JAX-RS does things such that things you're grabbing from the request become method parameters before the method is called rather than the method just taking a request object.

JAX-RS makes you define what you want to send and what you want to receive in the method signature. I totally agree that people should start with thinking about what they want from an API, what to send, and what to receive. But is starting with OpenAPI something that would be making up for languages/frameworks that don't do development in that way naturally?

----------

Just to show I'm not picking on Go, I'm pretty sure one could create a Go framework more like this, I just haven't seen it:

    type GetPersonRequest struct {
        Request `path:/people/{personId}`
        PersonId int `param:path`
    }
    func GetPerson(personRequest GetPersonRequest) Person {
        return db.GetPerson(personRequest.PersonId)
    }

I think you'd have to have the request object because Go can annotate struct fields (with struct tags), but can't annotate method parameters or functions (but I could be wrong). The point is that most languages/frameworks don't have the spec information in the code in an easy way to reflect on like JAX-RS, ASP.NET APIs, and some others do.

[thiht]

I absolutely hate the approach of scattering routing instructions everywhere via annotations. Nothing beats a router.go file with all the endpoints declared in the same place. Routing annotations is a bad idea that caught up just because it looks clever.

Looking for the handler for ˋGET /foo/{fooID}/barˋ is terrible in a codebase using annotations.

[avolpe]

For the happy path, the Java code works great, but a good open API spec also includes the following:

- examples, they are a pain to write in Java annotations.

- multiple responses, ok, invalid id, not found, etc.

- good descriptions, you can write descriptions in annotations (particularly post Java 14) but they are overly verbose.

- validations, you can use bean validation, but if you implement the logic in code it's not easy to add that to the generated spec.

See for example this from springfox https://github.com/springfox/springfox/blob/master/springfox...

It's overly verbose and the generated open API spec is not very good.

[jpalawaga]

swaggest allows you to define your inputs and outputs, and generate docs from them.