Сhecklist for your next IT integration
Whether you are an Enterprise, a Bank, a Fintech start-up, you are expecting to make your next API integration with a 3rd-party provider Fast, Stable, Predictable, Secure, Inexpensive. Just follow the checklist below, ask your partner company to answer all the questions, state it in the contract and be sure — you got everything under control.
1. Communication
- Who is the contact person from the 3rd party side? Who is responsible for the integration or just the one you can get information from.
- What is the suitable communication channel? It can be Email, Slack, Whatsapp, Help desk system, Phone, etc.
- 🎁 Bonus: Set up how often you would communicate with the contact. Note: it’s important not to overflood the counter-party with tons of messages during the progress. Your communication then can be broken very soon.
2. Connectivity
- What a connection type with the provider would be? Synchronous or asynchronous? Will the response come immediately or will it be available over some time?
- What is the technical type of the connection? REST, SOAP, Pub/Sub, any other?
- What is the IP/hostname of the prover’s main server?
- How would the security of the connection be provided? TLS/SSL, closed channel, etc.?
- How will your system be notified about the change of the remote objects’ statuses/states? Is it webhooks or a polling technique?
- If the provider initiates connection from their side, what IP address would it be coming from? So you can whitelist it from your side.
- 🎁 Bonus: Will your external IP be whitelisted on the provider’s platform? Or is it a public server? Make sure your partner company stands devoted to security as well.
Service level agreement (SLA) is an agreement in the contract in terms of technical guarantees the 3rd party is ready to provide. Service level objective (SLO) is each technical metric provider has a guarantee for.
If you are a math fan: SLA = SLO 1 + … + SLO N.
3. Common SLA
Common SLO’s will be listed here. You will find other SLO’s down below in the text.
- What’s the general availability of the partner system? 99,9/99,99/99,999? How many “nines”?
- API rate limit — what maximum number of requests per second is guaranteed to be held by the partner server?
- What is the maximum latency (ms) for each request guaranteed?
- 🎁 Bonus: What is average latency? What latencies are for percentiles: P95, P99?
- For webhooks. What is the normal delivery rate per second of the requests coming from the partner server? What is the peak number?
- For webhooks. What policy does the partner have for cases when your listening server is not responding? What will provider do, how it guarantees the delivering of events? In what time period?
4. Data
- Is there any size limitation for each request message?
- What portions of your data the partner company will be storing? How is this data protected?
- 🔔 SLO. For how long the partner is intending to store data from you? For how long logs will be stored?
- 🔔 SLO. How many business objects can your partner company hold? For example, how many banking accounts can be created? How many transactions can be created per day/month?
- Does the partner perform idempotent checks of the incoming requests?
- 🎁 Bonus: When creating new business objects, does partner ask for your related internal ID’s? Are there any format restrictions?
- Should request messages be encrypted? If yes, which algorithm would it be?
- 🎁 Bonus: If encryption is used, will partner provide any SDK/library/example of messages encryption/decryption?
- 🎁 Bonus: If encryption is used, how signing key would be transferred? How a signature would be delivered along with the request message?
5. Authentication
- What is the type of authentication? API key, user/password pair, any other?
- For how long are the credentials valid?
- What is the procedure of changing credentials? Is downtime needed for that?
6. Documentation
- Is API documentation available? What is a portal address/credentials?
- 🎁 Bonus: When was the documentation changed the last time?
- 🎁 Bonus: Does partner have a blog containing description of updates, new upcoming features, releases?
7. Support
- 🔔 SLO. For how long will the current API be supported? The guaranteed amount of time.
- What is the lifecycle of the API version usually?
- What is the procedure of switching to the new version?
- What type of support is available?
- 🔔 SLO. For how long the support is available?
- 🔔 SLO. How many hours of support per month are guaranteed?
- 🔔 SLO. What is the response time of the support team?
- 🎁 Bonus 🔔 SLO. What is the average solution delivery time of the support team?
- What are the maintenance windows? You have to deal your best windows for yourself.
- 🔔 SLO. How often and for how long the planned maintenance is done?
- 🔔 SLO. How would you be notified about the planned/urgent maintenance? What are the communication channels? Who will be notified?
8. Testing
- Is there any sandbox environment?
- 🔔 SLO. What functionality scope the sandbox environment will guarantee?
- For sandbox: if interaction from the partnering side is necessary? Is it automated or manual?
- 🔔 SLO. When working with the sandbox and the interaction from the partner is needed — what is the contact and what is guaranteed time of the response?
9. Launch
- Is there any acceptance phase before the launch?
- What does the acceptance phase consist of? What is a testing plan, test cases?
- 🔔 SLO. What is the general timeline for an acceptance?
- What is the procedure of starting the production usage?
- What is production IP address/hostname, credentials?
- 🔔 SLO. When you request the production environment, what time is guaranteed for it to be ready?
10. Deal the price
- What support plans are available?
- What is the cost of upgrading the support plan?
- What is the cost of additional support beyond the contracted support plan?
- What is the cost of any additional features?
- What are any additional costs that can popup during the testing and the production system exploitation?
🏁 That’s it. Now you are strongly equipped with every important integration detail. Feel free to raise your concern level if the partner company cannot answer any of the questions above.
It’s time to Start! Have a nice integration 🖥
P.S. Did I miss something? Please let me know in comments section.
Photo by Volodymyr Hryshchenko on Unsplash. Modified by the article author.