API is the abbreviation for an application programming interface.
In simple terms it is an “electronic handshake” between two systems.
This electronic handshake defines a “common language” for the systems to talk to each other – i.e. for data to pass through. In the data-heavy world of commercial real estate (CRE), it is most commonly used to pass data between two systems.
Types of APIs
- Private: An API is for internal company user only
- Partner: Non-arms length third parties can use the API. For example, if you are an approved third-party developer you can pass data in or receive data from Gmaven
- Public: Using a special key (API token or customer status validation) you as a member of the public can use the API.
API documentation and good practices
As with any formal relationship, the API’s documentation is very important. The documentation generally explains the services the API offers and how to use those services. (That is, this documentation lists the fields, indicating what minimum required information is required to successfully pass a message, and what that the data for each field should look like, and not look like). This ensures that each party does not have to understand the intricacies behind each system – a strong benefit of an API.
A good API will also provide detailed feedback in the event that the wrong data is passed – e.g. data that fails the required shape of data approved for that field.
API documentation should also be “version controlled” – for example: on this day, the API changed, and these were the changes.
When parts of an API change, these changes should be explicitly and proactively documented. Further, as an additional good practice, these changes (especially “breaking changes” should be communicated to third parties relying on the API)
It is a bad practice to make breaking changes to an API (for example adding required fields) without letting the partners to the API know ahead of time.
Here, from Stack Overflow, is an article unpacking best practices for REST API design