Getting Started – Lesson 6
Developer Resources
Building an API integration can be challenging, especially if you’re working with a new API. But don’t despair! Developer resources like Dev Centers, Developer accounts, SDKs, and documentation can make the process quick and easy relatively painless. Fortunately, you’ll find some level of developer resources for practically any API you’ll encounter these days.
You see, companies love it when developers build integrations with their product. Not only can API integrations provide a valuable source of transactional revenue for a product, it can also make a product “stickier” — when folks go through the time and expense of building an API integration with a product, they’ll likely continue to use that product for years to come. If competing products offer similar functionality at a similar price, API functionality and developer experience (the quality and volume of developer resources available) can even be the reason that one product is chosen over another.
In this post, we’ll take a look at four types of developer resources that companies often provide to promote a great developer experience with their APIs:
- Dev Center
- Developer accounts
- SDKs (client libraries)
- Documentation
Understanding how to effectively use these resources can be the difference between struggling to build a mediocre API integration and efficiently building a high-quality API integration.
Dev Center
Beginning work on a new API integration? Do not pass Go, do not collect $200 — go straight to that product’s Dev Center. The Dev Center (sometimes referred to as a “Dev Portal”) is the website that contains all developer resources for a given product. Here are a few examples:
- Docusign: https://developers.docusign.com
- Smartsheet: https://developers.smartsheet.com
- AWS: https://aws.amazon.com/developer
A simple Google search for “[product name] developer center” (where [product name] is the name of the product you want to integrate with) should return the link the product’s Dev Center. Bookmark the Dev Center site — you’ll be using it a lot as you build your API integration.
Within a product’s Dev Center, you’ll find information about everything from Developer accounts, to getting started, to SDKs, to code samples, to API documentation, to support — sometimes even interactive tools you can use to test API calls. For example, the following screenshot shows the Smartsheet Dev Center.
Developer accounts
In API Security and Authentication, we learned that most APIs limit access only to entities (users or applications) that are known to the corresponding system. This means that in order to call an API, you’ll first need to have an account in the corresponding system. For example, if you want to call the DocuSign API, you’ll need a DocuSign account.
But what if you don’t want to pay for a real DocuSign account just to build and test your API integration? Have no fear — Developer accounts are here! A Developer account (or “Dev account”) is a free account that you can use to build and test an API integration in a sandbox outside of a system’s production environment.
Creating a Dev account
Creating a Dev account is simple. First, on the main page of the Dev Center, look for a link or button labeled “Developer Account” or “Create an Account” or “Register” or “Developer Program” or something similar. For example, the DocuSign Dev Center features a Developer Account button in the page header that gives you the option to select Create account.
Select that link or button and then provide the required information. Usually you’re only required to provide basic contact info, as shown in the following DocuSign form.
It’s as simple as that. Once you’ve created your Dev account, you’ll be able to login and generate an API access token. (The Getting Started section of the API docs should tell you how to do this.) At that point, you’ll have an account that you can use to issue (authenticate) API calls.
Keep in mind…
- Dev accounts are intended purely for development and testing — never use a Dev account for anything real. (For example, don’t use a DocuSign dev account to send/sign the bill of sale when you sell your car.) Not only could your account be suspended for violation of terms, but by nature, Dev accounts aren’t typically as stable as paid accounts, and don’t include the same level of support.
- Dev accounts are often full-featured accounts (i.e., with all available product features are enabled — even “premium” features that come at an additional cost in the production environment). If you need a feature that’s not enabled on your Dev account, you can usually get that feature enabled (at no cost) by contacting the company’s support team and requesting that it be enabled. However, be prepared to pay extra for premium features when your integration is deployed to the production environment.
SDKs (aka client libraries)
The acronym “SDK” originated back in the day when an SDK was literally a Software Development Kit (SDK), consisting of one or more CDs along with hardcopy (printed) documentation. Fast-forward to today, and SDKs are no longer “kits” consisting of CDs and printed docs — thank goodness! In the current context of API development, the term SDK (sometimes called a client library) refers to a language-specific or platform-specific software library for building API integrations. Products with APIs will usually provide SDKs (client libraries) for a variety of languages. For example, Smartsheet provides SDKs in C#, Java, Node, Python, and Ruby (as shown within their Dev Center).
What’s so great about SDKs?
Let’s say you’re a Python developer who building an integration using the Smartsheet API. You’ve got a couple of options:
Option 1: Write all code entirely from scratch — using the Python requests library to manually construct and submit each API request.
Option 2: Download the Smartsheet Python SDK and just write code that calls functions in the SDK to perform the necessary API operations.
Trust me when I say that pursing Option 2 (using an SDK) will save you a lot of time and effort! At a minimum, an SDK will expose functions you can call to run the various API operations — thereby saving you from having to write all that code yourself. Good SDKs will also include robust error handling, retry logic, and other functionality that can improve the efficiency of an API integration.
Using an SDK
You’ll find information about SDKs in the Dev Center for the product you’re integrating with. Simply find the SDK for your language of choice, and follow the instructions provided to download, install, and use it. Most Dev Centers will include sample code (sometimes even full sample applications) that show how to use an SDK.
Keep in mind…
A majority of SDKs these days are “open source” — i.e., the full SDK — including all source code, releases, instructions for use, etc. — are published to GitHub. If you’re using an SDK that’s published to GitHub:
- The README.md file (displayed on the main page of the GitHub repo, below the file tree) should contain detailed info about SDK prerequisites, installation, and usage.
- Keep an eye out for a ‘test(s)’ or ‘integration tests‘ or ‘samples‘ folder in the GitHub repo (or something similarly named). The code found in such folders often contains good examples of how to call various functions within the SDK.
- The Issues page within the GitHub repo shows any problems that others have reported with the SDK, and provides a way for you to report any problems you may encounter.
- The Pull requests page within the GitHub repo shows any changes/additions that others have proposed to the SDK. (Feel free to fork the repo and submit your own pull requests if there are changes you’d like to see made.)
SDKs only get updated periodically, even though the underlying APIs evolve frequently (e.g., API operations are added and updated quite often). This means you may occasionally see situations where an API (according to the documentation) supports certain functionality that the corresponding SDK does not yet support. This just means that the SDK hasn’t yet been updated to reflect the latest and greatest API. In this case, you can either: 1) wait for an SDK update to be published or 2) update your copy of the SDK to include the desired functionality.
The following screenshot shows the Smartsheet Python SDK (README.md) in GitHub.
Documentation
When working with a new API, you may be tempted to jump right in and start writing code. Don’t do it!
Imagine you’re visiting Disneyland for the first time. Sooooo many rides, sooooo many food options, a million different walkways leading every which way! You could spend your day wandering around aimlessly, leaving it entirely up to chance what you find (and what you don’t find!)…or you could review a park guide map and plan your day. Which option will deliver a better experience?
When you’re building an API integration, the documentation IS your guide map. Take time to review the docs before you start writing code. Doing so may feel like wasted time in the moment, but it’ll save you tons of time and effort down the road!
Key components of documentation
I typically look for the following types of info in my first pass of any API docs:
- Introduction / Overview:
- Getting Started:
- What’s the process for getting started with using the API?
- How do I create a Dev account?
- How do I generate an API access token that I can use to authenticate my API calls?
- API features & functionality:
- What types of authentication are supported?
- What restrictions are enforced for API usage (e.g., rate limiting)?
- Which HTTP status codes may be returned in API responses and how should they be handled?
- API reference:
- What types of API operations are supported?
- Are the API operations that my use case requires available?
- Tools:
- Are there any interactive tools that I can use to test/try various API operations (e.g., like the DocuSign API Explorer)?
- Tutorials and/or Sample Apps:
- Are there any tutorials or sample apps that align well with my use case?
- SDKs:
- Is there an SDK for my language of choice, where do I find it, and how do I use it?
- Support info:
- How do I get help if I have questions about the API?
So there you have it…
…a brief introduction to Developer Resources. Working with a new API can be challenging, but knowing how to get the most out of Dev Centers, Developer accounts, SDKs, and documentation can make all the difference.
Congratulations!
You’ve reached the end of the Getting Started series! Next, up-level your skills by learning about some Tools that’ll make using APIs a breeze! But first — a quick knowledge check:
