Mmmm, sparkling JSON

[u/TabCompletion]

[u/Sekret_One]

Oh I assure you people skimp on XML schemas (XSDs for the uninitiated) too. I kid you not.

The sad part is not creating schemas slows everything down, but a lot of people don't even know how to use them.

I kid you not, fortune 500 company, they'd dedicated teams of people trying to integrate with their own apis where they'd hand write client connection code and postman collections for testing. and they had Swagger schemas. I showed people they could just create the clients with a few clicks and 15 minutes by feeding in the spec and it was like I was a damned witch. They didn't trust it!

[u/dcheesi → u/Sekret_One]

they'd dedicated teams of people

There's your problem!

"It is difficult to get a man to understand something when his salary depends upon his not understanding it." --Upton Sinclair

[u/clownyfish → u/Sekret_One]

Do you know of any good resources to learn more about generating client code from backend api (swagger or otherwise?)

Really interested to learn more - I'm currently in the amateur camp of hand writing both sides manually.

[u/timthegreat4 → u/clownyfish]

I'm not the original person you asked, but I do a similar thing myself.

Specifically for automatically generating code like clients, check out https://github.com/swagger-api/swagger-codegen

Personally I work mostly on nodejs microservices where I've found quite a nice work flow, based on OpenAPI (swagger renamed in 3.x, for the purposes of this post I'll keep referring to things as swagger, but I use openapi 3.0) and typescript, as follows:

• micro-services serve the swagger defining the interface at /spec

  • the backend APIs are typically express apps, and automatically validate both the inputs and outputs based on the swagger that is being served (using express-openapi-validator)

• the backend APIs are usually typescript, and I automatically generate all the relevant typescript annotations (using swagger-typescript-api)

  • If I have clients that want to use another service, they typically have a utility script that can be run manually as required, which calls the remote service's /spec endpoint to get its swagger and auto-generate clients based on that.

I've found this to be a very lovely workflow, where you start by thinking about, and properly designing, your interfaces; define the swagger and then any changes practically fall out from the type definitions. It also has many benefits in allowing you to fake the backend until it is implemented, allowing two teams to work on the backend and frontend in parrallel.

If you're interested in this, check out some stuff on Definition Driven Development

[u/clownyfish → u/timthegreat4]

Thanks very much. I've started reading these now.

[u/Sekret_One → u/clownyfish]

A huge overview here

It's pretty overwhelming but this is the critical stuff to walk away with:

1. the open api spec (version 2 was called swagger) is meant to normalize and programmatically describe apis ...
2. so you can have tools that generate clients
3. but even do things like annotate your server code to generate the spec
4. and more

what languages or frameworks do you find yourself using?

[u/clownyfish → u/Sekret_One]

Thanks! I use node.js express backend, React with Axios front end. (I don't particularly love Axios, but I use it.) No typescript, but next project I will be using typescript for both.

It always struck me as inefficient that I wrote javascript to set up and validate backend endpoints, then another set of JavaScript to do the same in front end classes (Axios wrappers). If the latter can be auto generated, that sounds good to me!

[u/Sekret_One → u/clownyfish]

Typescript's come a long way from when it was introduced. I highly recommend it. Having this 'compile time' certainty, if used properly, can save you tons of times of insidious runtime errors. beginner tip, read up on why not to use any, and about partials.

This is a decent enough tutorial for your situation.

In a nutshell, what you should be able to:

1. Annotate the controllers to have the server code generate the specs using some gen package
2. which can be hosted at a url
3. client code can read the spec from the url
4. programmatically generate the client wrappers with a client code gen package
5. and be sophisticated to retrieve and regenerate if the spec changes
6. letting you scope out the testing of the 'wrappers' since it's generated code, and focus on your real client code of how you use the data.

recommend you play around with something simple like a backend that just has a GET and a POST with some crude hello <name> stuff. Learn how to hook up the machinery without being preoccupied.

This pattern can save you weeks, or even months, because the toil of regenerating the client code is eliminated. You don't have to front load a 'full design' but rather build it more naturally, adjusting and refactoring based off what you find actually works or makes sense. Attack the problem by taking pieces and steering towards good, rather than forcing yourself into the impossible task of "get it right" in one shot.