In addition to being stable over time, APIs need to be internally consistent. I’ve seen many APIs that change parameter names or methods of POSTing data, depending on the endpoint that is being used. Instead, you should handle common parameters globally within your API and use inheritance or a shared architecture to reuse the same naming conventions and data handling consistently throughout your API. ✅ DO return a value that implements the ItemPaged protocol even if the service API currently do not support server driven paging.

python api design best practices

External-partnerThe API consumers with this audience are restricted to applications of business partners of the company owning the API and the company itself. Embracing ‚API as a Product‘ facilitates a service ecosystem, which can be evolved python api design more easily and used to experiment quickly with new business ideas by recombining core capabilities. The purpose of our „RESTful API guidelines“ is to define standards to successfully establish „consistent API look and feel“ quality.

General Background Reading + Watching

Moved Permanently – This and all future requests should be directed to the given URI. Accepted – The request was successful and will be processed asynchronously. A good example here for a secondary key is the shopping cart ID in an order resource. Returns all products matching the query passed as request input payload. APIs are encouraged to include a reference to the global schema for Money.

✅ DO follow the documentation guidelines unless explicitly overridden in this document. ✅ DO select a version number greater than the highest version number of any other released Track 1 package for the service in any other scope or language.

Provide Accurate API Documentation

As the number of tests increases, you need to ensure you process the correct test data consistently. One strategy for this is to prep the tests with a set of known good test data, perhaps loaded in before the suite runs and destroyed after the test is complete. As the codebase grows, you may want to concurrently run tests with real data and those known good data sets, but be sure to isolate those test runs with segmented data. REST, however, requires no specific interface definition, and offers wider support for data output types. If your API will interact with any non-Microsoft technology, SOAP may cause some interoperability issues.

While the order information is recommended for business events, it must be provided for data change events. The ordering information defines the change order of the data entity instances managed via the application’s transactional datastore. It is needed for change data capture to keep transactional dataset replicas in sync as source for data analytics. Technical timestamp of when the event object was created during processing of the business event by the producer application. Depending on the producer implementation, the timestamp is typically some milliseconds earlier than when the event is published and received by the API event post endpoint server — see below.

SHOULD consider to design POST and PATCH idempotent

Wherever possible, filtering in the API query rather than parsing it after you have the results back is better. RapidAPI is the world’s largest API Hub with over 4 Million developers and 35,000 APIs.

  • This is when a publisher defines a field to be of a different type that was already being emitted, or, is changing the type of an undefined field.
  • Service-agnostic concepts such as logging, HTTP communication, and error handling should be consistent.
  • Users collection, and will return the location and date of joining for kesh92.
  • Exactly, I was disappointed to see this was about HTTP APIs and had nothing to do with REST.

Well documented and announced multi-month deprecation schedules can be an acceptable practice for many APIs. It comes down to what is reasonable given the industry and possible consumers of the API.