harisrid Tech News

But why should I care about this stuff? Isn’t it enough to write good code and assume released APIs work as expected?

Hi all,

I want to share a couple of tips-and-tricks up my sleave to help you debug your API calls when you’re testing out your applications.

Frequently, you’ll run into needing to test API endpoints – typically /GET or /POST calls – for a customer-facing transactional application, for sending or retrieving data from an Enterprise data tier, or for triggering an event/action to an existing system. You’ll typically leverage open-source software or licensed-products such as ThunderClient ( VSCode ), Postman, or Insomnia to create small configurations to test API calls.

A Street-Fighting Checklist of Good Tips-and-Tricks – the Concise Version

1. Check VPN Connectivity
2. Check Environment configurations
3. Inspect SSL/Certificate Issues
4. Enable/disable SSL verification
5. Check API call layers
6. Check certificates, CA Certificates, and certificate paths
7. Headers check
8. Check the parameter string / query correctness
9. Install and update latest certificate libraries
10. Install and update the latest langauge SDKs and libraries
11. Leverage sandbox/isolated environments/containers ( Docker )
12. Introduce isolation levels
13. Verify payload correctness and comprehensiveness
14. Check security information
15. Set the correct method type
16. Passwords and Accounts Check
17. Compare to other calls
18. Sync with other developers : brainstorm and get ideas
19. Check certificate environment variables
20. Leverage CoPilot/AI textual tools
21. Generate code from Testing Clients ( e.g. Postman )
    

A Street-Fighting Checklist of Good Tips-and-Tricks – with explanations

1. Check VPN Connectivity
2. Check Environment configurations – e.g. passwords ( DB_PASSWORD ) or tokens values. Check the value is correct for the environment and that the environment is correct ( e.g. DEV, QA, PROD )
3. Introduce isolation levels
   • Network isolation – test if the issues persist when VPN connectivity is on versus off. Test
   • Client-side versus server-side isolation – if there’s an issue, ask if another developer can execute the same API calls from their machine. If they can execute the call, the issue is server-side – otherwise, there’s still the possibility of client-side issues.
4. Verify payload correctness and comprehensiveness
   • Oftentimes, payloads can be mal-formatted – key:value pairs are incorrect or not comprehensive enough. Check that payloads are fully correct.
5. Check security information
   • For AuthN, AuthZ, and other security reasons, API calls usually involve a subset of headers or BEARER tokens. Verify correctness
6. Inspect SSL/Certificate Issues
   • Issues could be due to the SSL ( Security Sockets Layer ) protocol, used for network encryption. Sometimes, you’ll be able to disable SSL and have request flowing. But other times, you’ll need to update client-side or server-side certificates ( or even CAs : Certificate Authorities ).
7. Enable/disable SSL verification – setting this parameter to FALSE can enable us to bypass client-side certificate checks or server-side certificate checks. It’s not recommended ( we loose encryption in-transit ).
8. Adding certificates to library paths – you may need to append server-side certificates on the library path your client-side applications recognize. This may entail appends to your cacert.pem files ( or others ). Can we experiment around and manually specify paths such as certificate_path or ca_certificate_path? Leverage libraries like Python’s certifi.where() method to view where your virtual env/runtime loads certificates.
9. Underlying Queries – are your queries correct? API calls include queries – either in their parameter string ( following the ? symbol ) or in request body payloads. The call itself can be correct, but the query executed can be incorrect, and you might be misinterpreting a 4xx error incorrectly.
10. Experiment with isolated environments – if applications don’t run locally, can we run in a more isolated environment? A container can be a good example, where we can set up a barebones minimal configuration. This isolates and helps us detect if misconfigurations arose up on local machines
11. Check your language’s SDKs and Libraries – maybe you need to upgrade or change the name of a web methods library ( e.g. requests for Python ). See commands like python3 -m pip install <latest_library>
12. Check API call layers – e.g. say you’re working with a REST client to contact another part of an Enterprise, but before doing so, you first need to connect to said Enterprise. Can we diagnose the underlying connection ( the layers below )? Issues can be upstream versus downstream.
13. Set the correct method – you’d be surprised how often a dev struggles with an API call because they’re executing a /GET that should be a /POST, or even a /POST that should be a /PUT. This happened with me on an attempt to execute /GET calls to GraphQL which should have actually been a /POST call.
14. Headers check – There’s a good number of headers – Authorization, Contnet-type, Accept, Content-Encoding, Keep-Alive, Accept-Language – passed on API calls. Make sure they are correct ( even ask if they’re needed – a lot of headers are superfluous and can be deleted ).
15. Passwords and Accounts Check – passwords are frequently rotated ( typically on a 90-day period ) within organizations.
16. Compare to other calls – if your current call doesn’t work, test two other calls whose structures share similarity. Like a puzzle, making equivalent changes until your call starts working ( or still doesn’t ). We can build off of what already works, from client-side.
17. Certificate environment variables – explicitly set the paths to certificates in your code ( or your local environment ).
18. Sync with other engineers – every engineer brings their different domain knowledge and ways of looking at problems. You might not see what another engineer sees, and vice versa.
19. Leverage Co-Pilot/AI Tools – we can provide code context on what an issue can be and get (nearRT) feedback within 1-2 minutes of what’s going on. On each iteration, add more debug and logging output – provide more context and help the AI tool output more accurate results.
20. Client-code generation – manual-developed calls have a high success rate from Postman or Thunderclient. What if we can use their auto-gen coding capabilities to write up quick unit tests?

More Best Practices

1. Folder structures – introduce a folder structure to API calls. Start organizing and grouping them. E.g. if you have API calls ( /GET and /POST ) for application one and for application two, introduce two folders with corresponding titles.
2. Upload your collections – surprisingly, you’ll also run into the scenario where multiple developers on a team use the same set of configurations, so go ahead and create collections and then share them on a central location!!!
3. Create environments – creating environments ( for DEV/QA/PROD ) and setting env-specific configurations ( e.g. passwords of hostnames ) is useful for quick testing. We can avoid creating duplicate API call tests if we leverage global configs.