Evolvable Graph API design

[OlgaPodo]

We are currently working on updating a set of guidelines specific for Graph APIs.

We also observed a need to list the best practices and patterns for evolvable API designs to accommodate changes more easily. We are thinking that it should probably include:

• Evolvable enums;
• Guidance on property versioning and other non-breaking changes.

Please add suggested topics to include in this issue.

[triplanedave]

Some other thoughts on ensuring longevity of an API and what constitutes breaking changes and should be planned for in design:

• Change a method or resource name. Ensure your names outlive internal product code names, avoid jargon, are consistent with other naming conventions for similar methods/resources.
• Changing invocation pattern. Ensure you plan ahead for required parameters so you aren't forced to add them later. Ensure new optional parameters don't change the default behavior of invocation.
• Changing responses structures. Select the proper data type to plan for future needs. e.g. select INT16 vs INT32 if you know you'll never grow beyond the needs for INT16. Down-sizing or changing response structure can break client apps.
• Changing response code. Ensure you're selecting the correct/consistent response code for the service. Clients rely on a specific response code for error/response handling.
• Changing Error content. Clients can and do parse error text for flow control, ensure you have complete error content and explanation.
• Throttling limits and 429 responses. Ensure you support throttling and document limits. Better to start low and raise limits than starting high and lowering limits that may break expected allowed calling volumes for a client app.
• Stale or cached data. If your API normally returns live data, changing to cached or stale data is a breaking change. Consider adding "lastUpdated" property to allow flexibility for data age by informing the caller of it's age.