Welcome!

Microservices Journal Authors: Plutora Blog, Pat Romanski, Liz McMillan, Lori MacVittie, Carmen Gonzalez

Related Topics: Java, Microservices Journal

Java: Blog Feed Post

The API Lab

Isn’t it about time for more creative solutions around API documentation?

Promotion is a problem faced by every API developer. Long nights of coding have given form to the stroke of genius you had six months ago in the cafe. You’ve just written the API that will serve as the front door into your application. But how do you document this so that your peers will use it—and hopefully make you rich in the process?

Java had Javadoc, an innovation that managed to strike a surprisingly effective balance between ease of use and systematization (three cheers for strong typing and static binding). Web services “solved” the interface definition problem with WSDL, a standard only its authors could love (and some of these won’t admit to participating in conception). To the registry crowd was left the task of devising clever ways to document a SOAP API around the torturous abstractions of WSDL so that humans could grok it as effectively as the machines. Few would argue that their solutions were, well, solutions.

RESTful APIs neither benefit nor suffer from formalized approach and automation. Every so often WADL pokes its head up, only to be knocked decisively back into its hole in a community game of Standards-Whac-A-Mole. REST is—and indeed, has always been—a style that resists any formalism that threatens its simplicity and accessibility. For this, above all, the community deserves praise.

But this does leave a hole around documentation. APIs tend to be described-by-wiki, which can be great or just awful, depending on a developer’s ability to write and discipline to update. Good ideas like ProgrammableWeb showcase both of these extremes; however, the site suffers in particular from out-of-date API descriptions which is too bad.

Outside of the eventual acceptance en masse of some kind of standardized wiki template for APIs (which I think is actually quite likely), we probably won’t see substantial change in API documentation soon. Minor changes, though, can still count for a lot, and it’s worth pointing these out.

Google, always an innovator to watch, create a lot of APIs. They recently published the Periodic Table of Google APIs, which as its name suggests is a clever way to visually categorize their API portfolio into groups like mobile, data, geo, etc. It’s a bit gimmicky, but it is also fun and actually inspired me to try some new Google APIs that I wasn’t aware of before.

So, isn’t it about time for more creative solutions around API documentation?

Read the original blog entry...

More Stories By Scott Morrison

K. Scott Morrison is the Chief Technology Officer and Chief Architect at Layer 7 Technologies, where he is leading a team developing the next generation of security infrastructure for cloud computing and SOA. An architect and developer of highly scalable, enterprise systems for over 20 years, Scott has extensive experience across industry sectors as diverse as health, travel and transportation, and financial services. He has been a Director of Architecture and Technology at Infowave Software, a leading maker of wireless security and acceleration software for mobile devices, and was a senior architect at IBM. Before shifting to the private sector, Scott was with the world-renowned medical research program of the University of British Columbia, studying neurodegenerative disorders using medical imaging technology.

Scott is a dynamic, entertaining and highly sought-after speaker. His quotes appear regularly in the media, from the New York Times, to the Huffington Post and the Register. Scott has published over 50 book chapters, magazine articles, and papers in medical, physics, and engineering journals. His work has been acknowledged in the New England Journal of Medicine, and he has published in journals as diverse as the IEEE Transactions on Nuclear Science, the Journal of Cerebral Blood Flow, and Neurology. He is the co-author of the graduate text Cloud Computing, Principles, Systems and Applications published by Springer, and is on the editorial board of Springer’s new Journal of Cloud Computing Advances, Systems and Applications (JoCCASA). He co-authored both Java Web Services Unleashed and Professional JMS. Scott is an editor of the WS-I Basic Security Profile (BSP), and is co-author of the original WS-Federation specification. He is a recent co-author of the Cloud Security Alliance’s Security Guidance for Critical Areas of Focus in Cloud Computing, and an author of that organization’s Top Threats to Cloud Computing research. Scott was recently a featured speaker for the Privacy Commission of Canada’s public consultation into the privacy implications of cloud computing. He has even lent his expertise to the film and television industry, consulting on a number of features including the X-Files. Scott’s current interests are in cloud computing, Web services security, enterprise architecture and secure mobile computing—and of course, his wife and two great kids.

Layer 7 Technologies: http://www.layer7tech.com
Scott's linkedIn profile.
Twitter: @KScottMorrison
Syscon blog: http://scottmorrison.sys-con.com

@MicroservicesExpo Stories
Here are a few questions to help you assess the scope of your release management challenges. Based on the answers to these questions, you can calculate your Release Management risk factor. This will help you understand what steps you need to take today to mitigate release management risks that accompany software development at scale. These 100 people don't have to be in a single group and the systems maintained don't have to be limited to a single group. Also, note that the systems supported...
DevOps approaches within “Unicorns” vary significantly from the reality of DevOps in the enterprise. Most enterprises manage portfolios of heterogeneous applications that are increasingly interconnected, delivered by global teams, at various stages of technology maturity, and are often encumbered by additional compliance and governance obligations. In his session at DevOps Summit, Dalibor Siroky, Director and co-founder at Plutora, will discuss the emerging and evolving experiences of Agile, Co...
It's a "given" in software development - release schedules always slip. Requirements shift, developers underestimate timelines, and quality assurance (QA) finds unexpected defects. Another law of software development is that final release dates are often inflexible. If a market or a holiday shopping season defines your release date you understand how important it is to meet a fixed timeline. Once you've promised a release to the business at the end of the quarter, you are under pressure to de...
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...
Lacking the traditional fanfare associated with any technology that can use the word "container" or mention "Docker" in its press release, Ubuntu Core and its new Snappy system management scheme was introduced late last year. Since then, it's been gaining steam with Microsoft and Amazon and Google announcing support for the stripped-down version of the operating system. Ubuntu Core is what's being called a "micro-OS"; a stripped down, lean container-supporting machine that's becoming more pop...
17th Cloud Expo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Meanwhile, 94% of enterprises a...
Cloud computing seems destined to be the way enterprises will use information technology. The drastic cost reductions and impressive operational improvements make the transition an unstoppable trend. The “What is cloud computing?” question now, however, seems to be morphing into “Where is cloud computing going?” While software-as-a-service (SaaS) providers see their market rocketing upward as the easiest and quickest path for cloud adoption, infrastructure-as-a-service providers are suffering...
SYS-CON Events announced today Isomorphic Software, the global leader in high-end, web-based business applications, will exhibit at SYS-CON's DevOps Summit 2015 New York, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Isomorphic Software is the global leader in high-end, web-based business applications. We develop, market, and support the SmartClient & Smart GWT HTML5/Ajax platform, combining the productivity and performance of traditional desktop software ...
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
There is no doubt that Big Data is here and getting bigger every day. Building a Big Data infrastructure today is no easy task. There are an enormous number of choices for database engines and technologies. To make things even more challenging, requirements are getting more sophisticated, and the standard paradigm of supporting historical analytics queries is often just one facet of what is needed. As Big Data growth continues, organizations are demanding real-time access to data, allowing immed...
Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities. Accordingly, attendees at the upcoming 16th Cloud Expo at the Javits Center in New York June 9-11 will find fresh new content in a new track called PaaS | Containers & Microservices Containers are not being considered for the first time by the cloud community, but a current era of re-consideration has pushed them to the top of the cloud agenda. With the launch ...
The world's leading Cloud event, Cloud Expo has launched Microservices Journal on the SYS-CON.com portal, featuring over 19,000 original articles, news stories, features, and blog entries. DevOps Journal is focused on this critical enterprise IT topic in the world of cloud computing. Microservices Journal 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. Follow new article posts on T...
SYS-CON Events announced today that MangoApps 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., 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. MangoApps provides private all-in-one social intranets allowing workers to securely collaborate from anywhere in the world and from any device. Social, mobile, and eas...
There are 182 billion emails sent every day, generating a lot of data about how recipients and ISPs respond. Many marketers take a more-is-better approach to stats, preferring to have the ability to slice and dice their email lists based numerous arbitrary stats. However, fundamentally what really matters is whether or not sending an email to a particular recipient will generate value. Data Scientists can design high-level insights such as engagement prediction models and content clusters that a...
The cloud has transformed how we think about software quality. Instead of preventing failures, we must focus on automatic recovery from failure. In other words, resilience trumps traditional quality measures. Continuous delivery models further squeeze traditional notions of quality. Remember the venerable project management Iron Triangle? Among time, scope, and cost, you can only fix two or quality will suffer. Only in today's DevOps world, continuous testing, integration, and deployment upend...
It was just two years ago, in March of 2013, that the PaaS company dotCloud decided to open-source its container technology under the name "Docker." Docker quickly became a hit, with Docker Meetups spawning weekly worldwide and downloads occurring at record-breaking rates. The dotCloud team quickly changed direction, renamed the company "Docker," and brought in new CEO Ben Golub in July 2013 to lead the new business model. At the time, Docker was about a twenty-person company. Fast-forward to to...
Chuck Piluso will present a study of cloud adoption trends and the power and flexibility of IBM Power and Pureflex cloud solutions. Speaker Bio: Prior to Secure Infrastructure and Services, Mr. Piluso founded North American Telecommunication Corporation, a facilities-based Competitive Local Exchange Carrier licensed by the Public Service Commission in 10 states, serving as the company's chairman and president from 1997 to 2000. Between 1990 and 1997, Mr. Piluso served as chairman & founder...
To manage complex web services with lots of calls to the cloud, many businesses have invested in Application Performance Management (APM) and Network Performance Management (NPM) tools. Together APM and NPM tools are essential aids in improving a business's infrastructure required to support an effective web experience... but they are missing a critical component - Internet visibility. Internet connectivity has always played a role in customer access to web presence, but in the past few years u...
Working with Big Data is challenging, especially when decision makers depend on market insights and intelligence from your data but don't have quick access to it or find it unusable. In their session at 6th Big Data Expo, Ian Khan, Global Strategic Positioning & Brand Manager at Solgenia; Zel Bianco, President, CEO and Co-Founder of Interactive Edge of Solgenia; and Ermanno Bonifazi, CEO & Founder at Solgenia, discussed how a revolutionary cloud-based BI along with mobile analytics is already c...
2015 is the 10th birthday of Ruby on Rails (or simply called Rails), the popular open source web application framework that uses the Ruby programming language. Ever since Rails burst on the scene a decade ago it has continued to scale up as an elegant way to build dynamic websites quickly and efficiently. Rails has garnered a strong following, especially among tech startups. In fact, some of the best known firms out there are using the framework to build their sites. Examples of elegant sites bu...