4 Things an API Should Do

You would be surprised at how little functionality some vendor APIs actually provide: can they actually connect your two systems? To figure this out, it'll help to know what an API is, and what to look for in a working, robust API.

When you ask a system implementer to connect two very different systems, they often have a standard response: 

"We have an API for that". 

That's great. But you should go a bit further. Verify that their API is up to the job by requesting the API documentation as part of the submission.  You would be surprised at how little functionality some vendor APIs actually provide: can they actually connect your two systems?

To figure this out, it'll help to know what an API is, and what to look for in a working, robust API.

What is an API?

So, what is an API? An API is a defined interface point into the software that allows a system-to-system interface to retrieve information from your system, or to push new information into your system.  Using an API to access a system is good practice to ensure that the internal business logic of a system is respected - only valid information is input, and well-formed information is output.

An API can have 4 major operations that follow the data lifecycle: Create - Read - Update - Delete.  But for most systems, it is best practice to not allow DELETE operations through an API.  Instead, Search is the operation that is most useful.

Create

All of the major business objects in a system should be creatable - a new Contact, a new Asset, a new journal entry, etc.  Sometimes, there is a hierarchy associated with the creation of business objects.  For example, you can't create an attachment in a Customer Relationship Management (CRM) system without having an associated Case or Contact or Account.  You need to know the identifier of the parent entity (see Search) to create the parent-child relationship between the two objects.  API documents will show POST methods to create new business objects.  Make sure the business objects you care about have POST methods.

Update

Sometimes there are fields or attributes in a record that you need to update in your system.  Through the API, there are two issues with Update.  If a business object exists, you need to identify the record through its unique identifier, and then change the specific field values for said record. 

An Update can be handled in an API through either an UPDATE or a POST request.  If you use a POST request, you are overwriting the entire record with new information.  An UPDATE request can use just the subset of fields that require an update.  Some more sophisticated software APIs support the UPSERT method, which will either update a record if it exists or create a new record if it didn't previously exist.

Read

You may need to extract information from your system, and the Read operation enables you to retrieve one or more records. If you look at any API documents, you will see GET methods to retrieve records from the system.

Search

Last but not least, SEARCH is a function that is often missing or not obvious in many APIs. 

When we are doing transactional updates to a system based on a message, we often need to find one or a subset of records that require an update.  Or, if we are retrieving records (READ), we often want to just retrieve records created since the last time we made a READ request - we need a time window that we search on.  So SEARCH methods are a critical mechanism for retrieving transactional information or selecting a subset of records to update.

Summary

When you are requesting proposals from your vendor community, here are two crucial questions to ask which could make a huge difference to the ease of your project:

• Question one: Does your system have an API?
• Question two: If yes, please provide the API documents

You may be pleasantly surprised at the openness of some systems, or astonished at how opaque some software vendors make their systems.  If you look for C-U-R-S in your proponent's API, you have a good differentiator to understand whether you are getting a modern system - or a repackaged legacy application.

If you need some guidance regarding your organization's use of APIs, you can book a free consultation with Spatial DNA.