|By Don MacVittie||
|April 22, 2013 09:15 AM EDT||
If you’ve ever developed for an enterprise IT department, and had to please the end user, you know very well that they don’t care about what your technical limitations are, they care about getting a tool that helps them do their job better. Oh some will commiserate with you about your challenges, and the best of the business side will compromise to get to a product that helps, even if it’s not perfect, but much like everyday consumers, they want what they want, and you either provide it or not. The thing is, in the enterprise, the pool of users is much smaller than for a commercial application, but the users are more focused on what they need, precisely because there are less of them.
On thing that many vendors fail to comprehend is that this “I need what I need and you provide it or you do not” approach applies just as strongly to enterprise developers. While most business to business (B2B) vendors (both hardware and software) understand the need to provide a useful, generally easy to learn user interface or command line, often that understanding does not extend to APIs.
Don’t make API consumers
into this guy.
There is a mentality of “We’re all developers here…”, which is true, but developers have different priorities. Just as the bulk of end users will not use an application that is poorly documented, non-intuitive, and complex, the same is true for the bulk of enterprise developers. They have a goal in mind, are trying to get their job done, and if your API is slowing them down or making their work harder, they will look for alternate ways to achieve their goals.
Oh, for sure there will be a small percentage that dig in and learn the API no matter how confusing and undocumented it is, for a variety of reasons ranging from earning geek cred to project requirements demanding it. But if given a choice, the vast majority of developers will seek an easier way to do what needs doing. They have timelines and deadlines, and will not let something like poor documentation interfere with those requirements.
Yes, stability and predictability of APIs is essential, without those items the toolset will not get used. But without documentation and an intuitive design with predictable types, requests, responses, etc. many developers won’t even get to the stability part. When the tool cannot be figured out in the time available, stability is entirely irrelevant.
So what do you need? Well, I have years of both writing and using APIs, and here are a few tips from me, no doubt others have a lot to add to the conversation:
- Cohesive design. Most APIs grow over time, but they need to adhere to standards set by the API docs, so that developers don’t waste time going “what is this completely different thing here…?” Variations need to be clearly documented.
- API reference. A quick reference to help developers understand how to make the API calls, what parameters are, what responses will be, standards supported, and requirements to use the API.
- A full blown “how to set this up”. Including clear documentation of the things required to use the API. Developers don’t care if you didn’t write part of the toolset – they expect that – but you’d better give them every bit of information they need to configure it for their development environment, including the parts you didn’t write. It’s your API, document all the steps to make it work.
- Samples. Not “Hello World” level, though that belongs in the API, but real use-case samples that delve in deep, preferably in steps so developers can learn without turning on the firehose.
- Input/output samples. In the world of SOAP/REST APIs, sometimes you just need to see what the final request going out needs to look like, and what to expect in the response document.
- High-level APIs. The more mondo-geeky your dev staff, the more likely that they want to expose each little tiny operation your product is capable of as a separate API. But honestly, enterprise developers don’t want to make 50 calls to do one thing common to their industry. It wastes time coding, it wastes network bandwidth, and it makes the application more laggy. To use my utility roots, if “Read a meter” is the command, THAT is what developers want to tell the API. They don’t (and shouldn’t have to) care how many steps that takes, they want the toolset to “just do it”. That is not to say that users do not want access to the individual steps of a process, only that they require one call to achieve one business function. If you don’t have a business layer, go write one. Now.
- Rockstar support. Seriously, if you want people to use the tool, then you have to give them a way to get solid answers. Places like StackOverflow are great for things a large number of people are using, but for your highly specialized API, not so much. So you have to provide it – in a community, with tech support, whatever way works best, but when stuck, people need their questions answered, not to paw through docs hoping to find some vague reference.
- Cohesive communications and constant feedback. Getting out there via social media, blogging, meetups, whatever, and talking about changes coming to APIs, new uses some customers have found for the APIs, bugs that are in-line to be fixed and workarounds are pretty darned important. Users want to be informed, and silence about the APIs kind of implies a lack of support going forward – whether that implication is accurate or not, it is perceived. And feedback is where the best ideas for improvements come from. The person who just struggled through implementation of the API for the first time has a unique view on what could be better, and needs a communications mechanism to make those recommendations. Meanwhile, the person whose dedicated a couple of years to production use of the API might well understand the real-world implications of the design better than the original analysts who wrote it up. Again, a feedback mechanism is required.
In the end, the point of an API is to get people to use it. Invest in the API, treat it like a product, even if in your business case it is a feature, not a product. It was developed for a reason, give IT the tools to make that reason real.
And save us all a ton of time trying to figure out how to use it, so we can focus on the overall application, not your tiny bit of it.
In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, president of Intellyx, panelists Roberto Medrano, Executive Vice President at Akana; Lori MacVittie, IoT_Microservices Power PanelEvangelist for F5 Networks; and Troy Topnik, ActiveState’s Technical Product Manager; will peel away the buzz and discuss the important architectural principles behind implementing IoT solutions for the enterprise. As remote IoT devices and sensors become increasingly intelligent, they become part of ...
May. 28, 2015 09:45 AM EDT Reads: 1,582
This is the final installment of the six-part series Microservices and PaaS. It seems like forever since I attended Adrian Cockroft's meetup focusing on microservices. It's actually only been a couple of months, but much has happened since then: countless articles, meetups, and conference sessions focusing on microservices have been delivered, many meetings and design efforts at companies moving towards a microservices-based approach have been endured, and five installments of this blog series ...
May. 28, 2015 09:30 AM EDT Reads: 2,450
In the first four parts of this series I presented an introduction to microservices along with a handful of emerging microservices patterns, and a discussion of some of the downsides and challenges to using microservices. The most recent installment of this series looked at ten ways that PaaS facilitates microservices development and adoption. In this post I’ll cover some words of wisdom, advice intended for individuals, teams, and organizations considering a move to microservices. I've gleaned...
May. 28, 2015 09:00 AM EDT Reads: 2,661
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo in Silicon Valley. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 17th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading in...
May. 28, 2015 09:00 AM EDT Reads: 2,468
The release of Kibana 4.x has had an impact on monitoring and other related activities. In this post we’re going to get specific and show you how to add Node.js monitoring to the Kibana 4 server app. Why Node.js? Because Kibana 4 now comes with a little Node.js server app that sits between the Kibana UI and the […]
May. 28, 2015 09:00 AM EDT Reads: 447
You often hear the two titles of "DevOps" and "Immutable Infrastructure" used independently. In his session at DevOps Summit, John Willis, Technical Evangelist for Docker, will cover the union between the two topics and why this is important. He will cover an overview of Immutable Infrastructure then show how an Immutable Continuous Delivery pipeline can be applied as a best practice for "DevOps." He will end the session with some interesting case study examples.
May. 28, 2015 09:00 AM EDT Reads: 1,711
It's 2:15pm on a Friday, and I'm sitting in the keynote hall at PyCon 2013 fidgeting through a succession of lightning talks that have very little relevance to my life. Topics like "Python code coverage techniques" (ho-hum) and "Controlling Christmas lights with Python” (yawn - I wonder if there's anything new on Hacker News)...when Solomon Hykes takes the stage, unveils Docker, and the world shifts. If you haven't seen it yet, you should watch the video of Solomon's Pycon The Future of Linux C...
May. 28, 2015 09:00 AM EDT Reads: 1,923
Even though it’s now Microservices Journal, long-time fans of SOA World Magazine can take comfort in the fact that the URL – soa.sys-con.com – remains unchanged. And that’s no mistake, as microservices are really nothing more than a new and improved take on the Service-Oriented Architecture (SOA) best practices we struggled to hammer out over the last decade. Skeptics, however, might say that this change is nothing more than an exercise in buzzword-hopping. SOA is passé, and now that people are ...
May. 28, 2015 09:00 AM EDT Reads: 3,503
SYS-CON Media named Andi Mann editor of DevOps Journal. DevOps Journal is focused on this critical enterprise IT topic in the world of cloud computing. DevOps Journal brings valuable information to DevOps professionals who are transforming the way enterprise IT is done. Andi Mann, Vice President, Strategic Solutions, at CA Technologies, is an accomplished digital business executive with extensive global expertise as a strategist, technologist, innovator, marketer, communicator, and thought lea...
May. 28, 2015 09:00 AM EDT Reads: 1,417
Virtualization is everywhere. Enormous and highly profitable companies have been built on nothing but virtualization. And nowhere has virtualization made more of an impact than in Cloud Computing, the rampant and unprecedented adoption of which has been the direct result of the wide availability of virtualization software and techniques that enabled it. But does the cloud actually require virtualization?
May. 28, 2015 09:00 AM EDT Reads: 1,966
Enterprises are fast realizing the importance of integrating SaaS/Cloud applications, API and on-premises data and processes, to unleash hidden value. This webinar explores how managers can use a Microservice-centric approach to aggressively tackle the unexpected new integration challenges posed by proliferation of cloud, mobile, social and big data projects. Industry analyst and SOA expert Jason Bloomberg will strip away the hype from microservices, and clearly identify their advantages and d...
May. 28, 2015 09:00 AM EDT Reads: 1,458
Bill Doerrfeld at Nordic APIs has written today about how APIs are evolving the B2B landscape. This is a particularly interesting article for me, because my personal background is working for an EDI provider, where I linked EDI processes from the private network to the Internet, over 15 years ago. Vordel was founded to allow new Web Services APIs to be used for B2B. Axway, a B2B software company, acquired Vordel in 2012 to link B2B with Web APIs. This caused a domino effect, with other API Manag...
May. 28, 2015 08:15 AM EDT Reads: 330
Cloud services are the newest tool in the arsenal of IT products in the market today. These cloud services integrate process and tools. In order to use these products effectively, organizations must have a good understanding of themselves and their business requirements. In his session at 15th Cloud Expo, Brian Lewis, Principal Architect at Verizon Cloud, outlined key areas of organizational focus, and how to formalize an actionable plan when migrating applications and internal services to the ...
May. 28, 2015 08:00 AM EDT Reads: 3,668
Python is really a language which has swept the scene in recent years in terms of popularity, elegance, and functionality. Research shows that 8 out 10 computer science departments in the U.S. now teach their introductory courses with Python, surpassing Java. Top-ranked CS departments at MIT and UC Berkeley have switched their introductory courses to Python. And the top three MOOC providers (edX, Coursera, and Udacity) all offer introductory programming courses in Python. Not to mention, Python ...
May. 28, 2015 07:00 AM EDT Reads: 1,071
Most companies hope for rapid growth so it's important to invest in scalable core technologies that won't demand a complete overhaul when a business goes through a growth spurt. Cloud technology enables previously difficult-to-scale solutions like phone, network infrastructure or billing systems to automatically scale based on demand. For example, with a virtual PBX service, a single-user cloud phone service can easily transition into an advanced VoIP system that supports hundreds of phones and ...
May. 28, 2015 07:00 AM EDT Reads: 2,849
Containers Expo Blog covers the world of containers, as this lightweight alternative to virtual machines enables developers to work with identical dev environments and stacks. Containers Expo Blog offers top articles, news stories, and blog posts from the world's well-known experts and guarantees better exposure for its authors than any other publication. Bookmark Containers Expo Blog ▸ Here Follow new article posts on Twitter at @ContainersExpo
May. 28, 2015 06:00 AM EDT Reads: 1,144
Let's just nip the conflation of these terms in the bud, shall we?
"MIcro" is big these days. Both microservices and microsegmentation are having and will continue to have an impact on data center architecture, but not necessarily for the same reasons. There's a growing trend in which folks - particularly those with a network background - conflate the two and use them to mean the same thing.
They are not.
One is about the application. The other, the network. T...
May. 28, 2015 06:00 AM EDT Reads: 1,097
Disruptive macro trends in technology are impacting and dramatically changing the "art of the possible" relative to supply chain management practices through the innovative use of IoT, cloud, machine learning and Big Data to enable connected ecosystems of engagement. Enterprise informatics can now move beyond point solutions that merely monitor the past and implement integrated enterprise fabrics that enable end-to-end supply chain visibility to improve customer service delivery and optimize sup...
May. 28, 2015 05:00 AM EDT Reads: 5,898
SYS-CON Events announced today that MetraTech, now part of Ericsson, has been named “Silver Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9–11, 2015, at the Javits Center in New York, NY. Ericsson is the driving force behind the Networked Society- a world leader in communications infrastructure, software and services. Some 40% of the world’s mobile traffic runs through networks Ericsson has supplied, serving more than 2.5 billion subscribers.
May. 28, 2015 05:00 AM EDT Reads: 1,366
The Internet of Things (IoT) promises to evolve the way the world does business; however, understanding how to apply it to your company can be a mystery. Most people struggle with understanding the potential business uses or tend to get caught up in the technology, resulting in solutions that fail to meet even minimum business goals. In his session at @ThingsExpo, Jesse Shiah, CEO / President / Co-Founder of AgilePoint Inc., showed what is needed to leverage the IoT to transform your business. ...
May. 28, 2015 04:00 AM EDT Reads: 6,710