I add boilerplate, definitions and conversions, places that need to know details, and documentation as needed. For instance, many past systems required that each layer, such as a middleware router or intermediate service, fully parse, process, and produce the full structure for RPC calls and messages. This is extremely fragile, difficult to maintain, and introduces a lot of unnecessary waste. We generally know this now as we pass JSON / XML objects around as parameters. I see APIs similarly. It is very good to define what APIs exist, after carefully designing the conceptual structure and baseline parameters (JWT token, modes, etc.). Often, the details of the API should not be fully baked into an API definition: Only the client and service app code need all the details.
Graph APIs illustrate this minimalist principle well: The basic API details are described, but the main parameters and results are potentially complex and somewhat fluid as new features & fields are added. The best documentation is a lot of example code with views of current results. That seems dissatisfying, but in practice, it is how a lot of things are developed.
Whenever possible, you should design with forward and backward compatibility, avoiding versioning. APIs should be able to evolve without breaking past usage. Sometimes mistakes are made and you do need versioning; usually, this is best done by updating everything as quickly as possible, retiring the old API, like a schema change in a database.
I add boilerplate, definitions and conversions, places that need to know details, and documentation as needed. For instance, many past systems required that each layer, such as a middleware router or intermediate service, fully parse, process, and produce the full structure for RPC calls and messages. This is extremely fragile, difficult to maintain, and introduces a lot of unnecessary waste. We generally know this now as we pass JSON / XML objects around as parameters. I see APIs similarly. It is very good to define what APIs exist, after carefully designing the conceptual structure and baseline parameters (JWT token, modes, etc.). Often, the details of the API should not be fully baked into an API definition: Only the client and service app code need all the details.
Graph APIs illustrate this minimalist principle well: The basic API details are described, but the main parameters and results are potentially complex and somewhat fluid as new features & fields are added. The best documentation is a lot of example code with views of current results. That seems dissatisfying, but in practice, it is how a lot of things are developed.
Whenever possible, you should design with forward and backward compatibility, avoiding versioning. APIs should be able to evolve without breaking past usage. Sometimes mistakes are made and you do need versioning; usually, this is best done by updating everything as quickly as possible, retiring the old API, like a schema change in a database.
developers.facebook.com/docs/graph...