Building Integrated Products
Interconnectivity between software products is ubiquitous. Everyday, new software services, products, and tools are born to provide value to their end users. As a result, specialization within products has become a necessary trait that young companies often adopt in order to provide better user experiences for their customers. Not many companies can provide product solutions that solve the entire spectrum of problems their users experience. To accommodate this, it is critical to build your product in a way that encourages other software products to integrate their solution into yours to fill your product gaps, further increasing your product’s value.
Take the project management tool Basecamp as an example. They pride themselves on the simplicity of their best selling product and believe that its simple nature is why their users love it so much. With that said, Basecamp also realizes the importance of helping their users solve a broad range of problems related to project management that they are experiencing. Yet, knowing this, they still don’t opt to develop an entirely new product line, or new product features. Instead, they provide value and solve these issues by enabling seamless integrations with other companies who have mastered solving these problems for the same user base (think Gantt Charts, project visualizations, developer tools, etc).
You too can be like Basecamp and increase the value of your product by making it interoperable with others that solve similar problems or can add additional functionality.
This sounds great, but as many product teams know, integrating with other products is more often problematic that delightful. Why is that exactly? Let’s take a look.
Better Developer Experiences
Developers rely on common patterns and best practices to build mental models about how systems work. As such, it’s not surprising that they seek out predictable and consistent open APIs that make it much easier on them to integrate other product offerings into their existing systems. When it comes to creating these easily integrated systems for yourself, here are four critical areas to focus on.
- REST based
- Documentation
- Testing
- Language Specific SDK’s
Now let’s took at deeper look at two of these critical areas: REST and Documentation.
REST Based API
Representational state transfer (REST) or RESTful web services is one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations. Other forms of Web service exist, which expose their own arbitrary sets of operations such as WSDL and SOAP.Without getting into the nitty gritty details of REST, simply put; modeling your API around the different resources your API deals with provides developers an easy way to understand how your API works. The less time a developer has to invest in learning your API- the better. Help yourself by making developers lives easier. Below are a few fundamental aspects of REST that are occasionally overlooked, but will make a big difference if done right:
- HTTP Methods — Use as intended, do not stray from best practices for GET, POST, PUT, PATCH, and DELETE.
- HTTP Status codes — Utilize the proper and most common status codes within your HTTP responses (200 Ok, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Error).
- Consistently modeled data — Have concrete data structures that your API consumes and produces; this makes it easy to represent in code.
- Detailed error handling — When something goes wrong and you have return a 400–500 status code, tell developers why.
- Single purpose endpoints — Ensure each HTTP endpoint serves one purpose. Do not have the behavior of endpoints change based on what you pass to it.
- Familiar Authentication — Utilize common authentication schemes such as OAuth2 flows (Implicit, password, authorization code, client credentials), Basic Authentication, OpenID Connect, Static API Key.
Documentation
Documentation is a critical aspect of an API. Our company Dropsource, along with many other name brand companies, has adopted the Open API spec as the preferred way to document APIs. Open API is an open source initiative to standardize the way developers describe APIs. We are big supporters of the Open API spec, and here are few of the reasons why:
- Having a universal standard for how companies document their APIs will greatly improve API consumption and interconnectivity.
- The spec is both human and machine readable which makes it easy for people to understand how the API works, but also allows other systems to understand how it works.
- A rise in automated tools could make product integrations seamless if all APIs were documented the same way.
I highly encourage everyone to check out Open API when considering API documentation. Not only will Open API specs help you create great documentation for other developers, but it will also help you build a better API by helping you to adopt best practices that fit within the Open API specs parameters.
Integrations at Dropsource
Our team at Dropsource aspires to give our community members the ability to build any app they want that integrates with whatever backend services they desire to use. This has led to our relentless pursuit to build a standardized interface for how mobile apps interact with remote data (for more on how this works inside Dropsource, see here). Whether your data comes from a custom API, or Facebook’s public API, or a MBaaS provider, at the end of the day, it is data that is being sent and received from someone else’s server to a mobile app. This pattern can, and has, been modeled in Dropsource.
APIs can be very complex, so whenever you can, I suggest you make the easy decision and follow an accepted pattern or framework. This makes it easier for both you and for others who will inevitably have to consume your API and integrate with another system or product. I hope this article lays the foundation for helping you to build APIs that are easy to work with and building better integrated products. Together, we can build better APIs that promote interconnectivity with other software products.
Please let me know what you think about the future of Open APIs, building integrated systems, and anything else, in the comments section below!
Nate Frechette is the CTO and Co-founder of Dropsource. Nate has experience building complex web and mobile applications, and still thinks the Buffalo Bills could win it all this season. Follow Nate at @natefrechette
