Click here to close now.

Welcome!

Microservices Journal Authors: Elizabeth White, Carmen Gonzalez, Pat Romanski, Liz McMillan, Jason Bloomberg

Related Topics: Virtualization, Java, Microservices Journal, Web 2.0, Big Data Journal, SDN Journal

Virtualization: Blog Feed Post

Your API Requires What??

Stability and predictability of APIs is essential, without those items the toolset will not get used.

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.

Read the original blog entry...

More Stories By Don MacVittie

Don MacVittie is Founder of Ingrained Technology, LLC, specializing in Development, Devops, and Cloud Strategy. Previously, he was a Technical Marketing Manager at F5 Networks. As an industry veteran, MacVittie has extensive programming experience along with project management, IT management, and systems/network administration expertise.

Prior to joining F5, MacVittie was a Senior Technology Editor at Network Computing, where he conducted product research and evaluated storage and server systems, as well as development and outsourcing solutions. He has authored numerous articles on a variety of topics aimed at IT professionals. MacVittie holds a B.S. in Computer Science from Northern Michigan University, and an M.S. in Computer Science from Nova Southeastern University.

@MicroservicesExpo Stories
SYS-CON Events announced today that Akana, formerly SOA Software, has been named “Bronze Sponsor” of SYS-CON's 16th International Cloud Expo® New York, which will take place June 9-11, 2015, at the Javits Center in New York City, NY. Akana’s comprehensive suite of API Management, API Security, Integrated SOA Governance, and Cloud Integration solutions helps businesses accelerate digital transformation by securely extending their reach across multiple channels – mobile, cloud and Internet of Thi...
Chef and Canonical announced a partnership to integrate and distribute Chef with Ubuntu. Canonical is integrating the Chef automation platform with Canonical's Machine-As-A-Service (MAAS), enabling users to automate the provisioning, configuration and deployment of bare metal compute resources in the data center. Canonical is packaging Chef 12 server in upcoming distributions of its Ubuntu open source operating system and will provide commercial support for Chef within its user base.
SYS-CON Events announced today that StorPool Storage will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. StorPool is distributed storage software that allows service providers, enterprises and other cloud builders to run data storage on standard x86 servers, instead of using expensive and inefficient storage arrays (SAN).
SYS-CON Events announced today that kintone has been named “Bronze 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 City, NY, and the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. kintone promotes cloud-based workgroup productivity, transparency and profitability with a seamless collaboration space, build your own business applic...
Modern Systems announced completion of a successful project with its new Rapid Program Modernization (eavRPMa"c) software. The eavRPMa"c technology architecturally transforms legacy applications, enabling faster feature development and reducing time-to-market for critical software updates. Working with Modern Systems, the University of California at Santa Barbara (UCSB) leveraged eavRPMa"c to transform its Student Information System from Software AG's Natural syntax to a modern application lev...
SYS-CON Events announced today that Site24x7, the cloud infrastructure monitoring service, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Site24x7 is a cloud infrastructure monitoring service that helps monitor the uptime and performance of websites, online applications, servers, mobile websites and custom APIs. The monitoring is done from 50+ locations across the world and from various wireless carr...
DevOps tasked with driving success in the cloud need a solution to efficiently leverage multiple clouds while avoiding cloud lock-in. Flexiant today announces the commercial availability of Flexiant Concerto. With Flexiant Concerto, DevOps have cloud freedom to automate the build, deployment and operations of applications consistently across multiple clouds. Concerto is available through four disruptive pricing models aimed to deliver multi-cloud at a price point everyone can afford.
SYS-CON Events announced today that B2Cloud, a provider of enterprise resource planning software, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. B2cloud develops the software you need. They have the ideal tools to help you work with your clients. B2Cloud’s main solutions include AGIS – ERP, CLOHC, AGIS – Invoice, and IZUM
SYS-CON Events announced today that Tufin, the market-leading provider of Security Policy Orchestration Solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. As the market leader of Security Policy Orchestration, Tufin automates and accelerates network configuration changes while maintaining security and compliance. Tufin's award-winning Orchestration Suite™ gives IT organizations the power and a...
SYS-CON Events announced today that Cloudian, Inc., the leading provider of hybrid cloud storage solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Cloudian, Inc., is a Foster City, California - based software company specializing in cloud storage software. The main product is Cloudian, an Amazon S3-compliant cloud object storage platform, the bedrock of cloud computing systems, that enables c...
In 2015, 4.9 billion connected "things" will be in use. By 2020, Gartner forecasts this amount to be 25 billion, a 410 percent increase in just five years. How will businesses handle this rapid growth of data? Hadoop will continue to improve its technology to meet business demands, by enabling businesses to access/analyze data in real time, when and where they need it. Cloudera's Chief Technologist, Eli Collins, will discuss how Big Data is keeping up with today's data demands and how in t...
The 5th International DevOps Summit, co-located with 17th International Cloud Expo – being held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA – announces that its Call for Papers is open. Born out of proven success in agile development, cloud computing, and process automation, DevOps is a macro trend you cannot afford to miss. From showcase success stories from early adopters and web-scale businesses, DevOps is expanding to organizations of all sizes, including the...
While DevOps most critically and famously fosters collaboration, communication, and integration through cultural change, culture is more of an output than an input. In order to actively drive cultural evolution, organizations must make substantial organizational and process changes, and adopt new technologies, to encourage a DevOps culture. Moderated by Andi Mann, panelists will discuss how to balance these three pillars of DevOps, where to focus attention (and resources), where organizations m...
ProfitBricks has launched its new DevOps Central and REST API, along with support for three multi-cloud libraries and a Python SDK. This, combined with its already existing SOAP API and its new RESTful API, moves ProfitBricks into a position to better serve the DevOps community and provide the ability to automate cloud infrastructure in a multi-cloud world. Following this momentum, ProfitBricks has also introduced several libraries that enable developers to use their favorite language to code ...
Change becomes the central principle of today’s enterprises, and thus business agility becomes the most important characteristic our organizations must exhibit. Agile Architecture lays out a best practice approach for achieving this agility – and thus drives and coordinates the other revolutions, as both digital and DevOps are about being able to deal with change better as well.
Dave will share his insights on how Internet of Things for Enterprises are transforming and making more productive and efficient operations and maintenance (O&M) procedures in the cleantech industry and beyond. Speaker Bio: Dave Landa is chief operating officer of Cybozu Corp (kintone US). Based in the San Francisco Bay Area, Dave has been on the forefront of the Cloud revolution driving strategic business development on the executive teams of multiple leading Software as a Services (SaaS) ap...
SYS-CON Events announced today that Vicom Computer Services, Inc., a provider of technology and service solutions, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. They are located at booth #427. Vicom Computer Services, Inc. is a progressive leader in the technology industry for over 30 years. Headquartered in the NY Metropolitan area. Vicom provides products and services based on today’s requirements...
How do you securely enable access to your applications in AWS without exposing any attack surfaces? The answer is usually very complicated because application environments morph over time in response to growing requirements from your employee base, your partners and your customers. In his session at 16th Cloud Expo, Haseeb Budhani, CEO and Co-founder of Soha, will share five common approaches that DevOps teams follow to secure access to applications deployed in AWS, Azure, etc., and the frict...
Today, the demand for new applications is growing at an unprecedented rate throughout lines of business and across industries. Customer expectations for mobile and e-commerce capabilities are transforming software development speed and quality into a competitive differentiator for even the most unlikely businesses. For existing software development shops, the proliferation of platforms, increasing need for total global uptime, and accelerating pace of industry disruption by fast-paced startups h...
Thought experiment: let’s say your app gets a message from somewhere, perhaps from another app, but you don’t know from where. The message contains the number 47 but no other information. What should your app do with the message? The answer: nothing. There’s no way for your app to make any sense out of a single datum with no context, no additional information or metadata about the datum itself. Now, let’s scale up this thought experiment to a data lake. There are a few common definitions o...