Defining endpoint systems

Endpoint systems are pretty easy to get your head around. They are the things being integrated. They are the pieces of business software that when combined via integration will create a cross-product experience for users that makes them better, faster, or more accurate at their jobs.

For a given integration project there has to be at least two endpoint systems--otherwise, what are you integrating? Two is usually what you'll end up scoping. You could potentially have more than two, depending on how you are separating concerns of project scope.

For a SaaS product integration, the good news is that one of those systems is YOUR PRODUCT. That's a huge advantage when it comes to defining data flow requirements, because you're dealing with a known product on one end of the integration.

It's an inefficient use of time to define every single possible attribute of a given endpoint system. Instead, it's best to focus on those attributes that will have the biggest impact on the project's complexity and timeline.

You'll need to dive into and document the following attributes, for each endpoint system:

  • Data File/Format - What will the data look like coming out of or going into the system? With modern APIs, this could be JSON. It could be tabular data in a CSV file. There are many ways data can be produced in a machine readable way.
  • Data Protocol - How will the integration have to communicate to retrieve or save that data? HTTP is very common with modern APIs, but SFTP, FTPS, SSH, and a number of other protocols are still widely used.
  • Authentication - How will the integration authenticate into the endpoint system? Does it use an open, standard authentication approach, like Oauth, or something proprietary or unique to that endpoint?
  • Known Capacity Limits - To the extent it's known at scoping time, does the endpoint have any capacity considerations? For examples, many modern APIs publish in their docs exactly how many API calls in a given time frame you're allowed to make without the API returning errors. This is particularly important if you expect large amounts of data movement.
  • Known Issues - Are there any other known issues about hosting, permissions, technology, or whatever that may impact the integration? The sooner you uncover complexity or uncertainty, the better. This is the catch-all question.

When you defining the scope for an integration project, it's also helpful to give each endpoint a simple, reference name. Sometimes an alias is even appropriate if you have multiple systems with the same or similar names.

You'd be surprised how many different names humans can come up with for different pieces of software. Later, when you're navigating the intricate details of the integration design, having a standard dictionary of names for the endpoint systems in play just removes one more potential point of confusion. You'll also use those names/aliases as part of expressing the data flows for the project.