What is triple response?

What's the best way to keep track of JSON request and response formats in a large web app project?

• (Though this question applies to web apps written in any backend languages and technologies, I am using Python/Django for the backend, so I may allude to this in the question details) I'm working on a large web application with a team. I have written hundreds of functions on the backend that expect a certain JSON request format, and return a certain JSON response format that the frontend should expect. (Obviously, as every web application with AJAX calls works this way). Anyways, our problem is that it is very hard to keep track of the JSON formats between the frontend and the backend! This is because they often change, and because the frontend programmers don't want to have to dig deep into the backend to dig up the request/response formats. It's a real pain. I've come up with a quick and dirty way of solving this. I write the JSON request and response formats in each function's (view's) docstring. Here's a simplified example of how I'm formatting a request or response example in the docstring: '{"article_id": <int>, "new_title": <str>, "new_description": <str>}' Then, I wrote a script that imports all the view modules in the backend, inspects each function of each view, parses the docstring for the JSON request/response, and outputs them all. This way, anyone working on the frontend can run the script and see all the formats. This method sucks, honestly. It's hard to navigate through the results. I have to constantly update the docstring to match any changes in the code. It's just a tedious mess. I'm sure this is a problem every large web application faces. What are some solutions? Maybe a script that takes a url as an input, finds the view that corresponds to that url, and returns that view's individual docstring? That way the frontend guys can just type the url in, which they know off the top of their heads.

• Answer:

  You seem to have two problems here: a reading problem ("How can developers easily look up the format of a given request?") and a writing problem ("How can I make sure the documentation always reflects reality?") You are currently, from the sound of it, doing your JSON parsing and result composition ad-hoc in your application code. What's more, I'm going to guess you're doing the same thing ad-hoc in the opposite direction in your client-side code. And you're also manually updating your documentation. That means you currently have three sources of truth, which is usually a recipe for inconsistency. A good answer here is . In this context, that means you specify your JSON API in a single place, and write code that generates client-side libraries to compose requests and decode responses, server-side libraries to decode requests and compose responses, and (possibly) documentation, which you can pretty up in a nice web UI if you like. I say "possibly" in the case of documentation because one approach is to use the documentation as the input to your code-generation tool, meaning people can just refer directly to that as needed and be 100% certain it's accurate. In practical terms, this means that the application code you maintain by hand will never deal directly in JSON requests or responses; it will instead deal in data structures that are consumed or produced by generated library functions, and those library functions will map the data structures to the appropriate JSON representations. One side benefit of this approach is that once you get it working it'll likely produce code with fewer bugs that's easier to test, by virtue of giving you a single place to globally apply fixes or to globally insert dummy data or response sanity-checkers. As for the reading problem, one approach to consider, if your developers are all used to working on a UNIXish command line, is to make your code generator spit out manual pages. Then a developer can just use the "man" command to view the API documentation for a particular endpoint. But it's probably also adequate to just put each endpoint's specification in a separate file with the same name as the endpoint. TL;DR: Generate your code from your documentation, not the other way around.