How do you design and plan your REST API's? Do you use Swagger or similar for generating documentation and generating stubs? Perhaps you even auto-generate big parts of the code / logic? Which kind of tests do you use? Do you test database interactions? How do you update your REST API if there's a lot of different implementations of the API around? What are your biggest "pain points" when developing or working with REST API's?
There are no wrong answers!
Top comments (3)
Background first: I’m a Python/Flask dev, it’s the only way I’ve written production REST APIs.
Currently my favorite method is using Flask-RESTPlus. This lets me write my API in Python and it generates a swagger.json (and hosts the Swagger UI if you want) from said code.
It’s my favorite method because documentation is super important and this way the documentation is derived from the code itself, so you know it’ll be correct! I find that doing it the other way around is hard to maintain, while I love the client libraries Swagger can generate, I can’t rely on the server code to be generated/updated from the docs without a lot of manual edits.
For testing I use pytest with a fixture that generates me a test database to do end-to-end tests and rolls back transactions between tests. It’s not the fastest but it is thorough.
Hey thanks for your reply! So basically your workflow now is: design -> code in Python/Flask -> end to end test on separate database -> generate docs. If I missed something please tell me!
Which part of this process causes the most friction / frustration for you and would you like to improve? Or would you keep everything as it is, no improvements needed?
I'm all about reducing repetition in code, my current process saves me the step of having to write documentation separately from implementation, but I still have to declare my database models separately from my user-facing models. Maybe one day I'll write a tool to streamline that.
I have the same issue with the Graph library I use in another project (off-topic, but related). I have to declare the same information in several different places whenever I make a change, it's easy to forget one and frustrating when it happens.