Click here to close now.

Welcome!

Microservices Journal Authors: Pat Romanski, Elizabeth White, Carmen Gonzalez, Liz McMillan, Roger Strukhoff

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
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...
Over the years, a variety of methodologies have emerged in order to overcome the challenges related to project constraints. The successful use of each methodology seems highly context-dependent. However, communication seems to be the common denominator of the many challenges that project management methodologies intend to resolve. In this respect, Information and Communication Technologies (ICTs) can be viewed as powerful tools for managing projects. Few research papers have focused on the way...
As the world moves from DevOps to NoOps, application deployment to the cloud ought to become a lot simpler. However, applications have been architected with a much tighter coupling than it needs to be which makes deployment in different environments and migration between them harder. The microservices architecture, which is the basis of many new age distributed systems such as OpenStack, Netflix and so on is at the heart of CloudFoundry – a complete developer-oriented Platform as a Service (PaaS...
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...
The widespread success of cloud computing is driving the DevOps revolution in enterprise IT. Now as never before, development teams must communicate and collaborate in a dynamic, 24/7/365 environment. There is no time to wait for long development cycles that produce software that is obsolete at launch. DevOps may be disruptive, but it is essential. The DevOps Summit at Cloud Expo – to be held June 3-5, 2015, at the Javits Center in New York City – will expand the DevOps community, enable a wide...
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...
Cloud Expo, Inc. has announced today that Andi Mann returns to DevOps Summit 2015 as Conference Chair. The 4th International DevOps Summit will take place on June 9-11, 2015, at the Javits Center in New York City. "DevOps is set to be one of the most profound disruptions to hit IT in decades," said Andi Mann. "It is a natural extension of cloud computing, and I have seen both firsthand and in independent research the fantastic results DevOps delivers. So I am excited to help the great team at ...
There is no question that the cloud is where businesses want to host data. Until recently hypervisor virtualization was the most widely used method in cloud computing. Recently virtual containers have been gaining in popularity, and for good reason. In the debate between virtual machines and containers, the latter have been seen as the new kid on the block – and like other emerging technology have had some initial shortcomings. However, the container space has evolved drastically since coming on...
Container frameworks, such as Docker, provide a variety of benefits, including density of deployment across infrastructure, convenience for application developers to push updates with low operational hand-holding, and a fairly well-defined deployment workflow that can be orchestrated. Container frameworks also enable a DevOps approach to application development by cleanly separating concerns between operations and development teams. But running multi-container, multi-server apps with containers ...
Converging digital disruptions is creating a major sea change - Cisco calls this the Internet of Everything (IoE). IoE is the network connection of People, Process, Data and Things, fueled by Cloud, Mobile, Social, Analytics and Security, and it represents a $19Trillion value-at-stake over the next 10 years. In her keynote at @ThingsExpo, Manjula Talreja, VP of Cisco Consulting Services, will discuss IoE and the enormous opportunities it provides to public and private firms alike. She will shar...
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...
The integration between the 2 solutions is handled by a module provided by XebiaLabs that will ensure the containers are correctly defined in the XL Deloy repository based on the information managed by Puppet. It uses the REST API offered by the XL Deploy server: so the security permissions are checked as a operator could do it using the GUI or the CLI. This article shows you how use the xebialabs/xldeploy Puppet module. The Production environment is based on 2 tomcats instances (tomcat1 &...
SYS-CON Events announced today that EnterpriseDB (EDB), the leading worldwide provider of enterprise-class Postgres products and database compatibility 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. EDB is the largest provider of Postgres software and services that provides enterprise-class performance and scalability and the open source freedom to divert budget from more costly traditiona...
How can you compare one technology or tool to its competitors? Usually, there is no objective comparison available. So how do you know which is better? Eclipse or IntelliJ IDEA? Java EE or Spring? C# or Java? All you can usually find is a holy war and biased comparisons on vendor sites. But luckily, sometimes, you can find a fair comparison. How does this come to be? By having it co-authored by the stakeholders. The binary repository comparison matrix is one of those rare resources. It is edite...
With the advent of micro-services, the application design paradigm has undergone a major shift. The days of developing monolithic applications are over. We are bringing in the principles (read SOA) hereto the preserve of applications or system integration space into the application development world. Since the micro-services are consumed within the application, the need of ESB is not there. There is no message transformation or mediations required. But service discovery and load balancing of ...
Do you think development teams really update those BMC Remedy tickets with all the changes contained in a release? They don't. Most of them just "check the box" and move on. They rose a Risk Level that won't raise questions from the Change Control managers and they work around the checks and balances. The alternative is to stop and wait for a department that still thinks releases are rare events. When a release happens every day there's just not enough time for people to attend CAB meeting...
T-Mobile has been transforming the wireless industry with its “Uncarrier” initiatives. Today as T-Mobile’s IT organization works to transform itself in a like manner, technical foundations built over the last couple of years are now key to their drive for more Agile delivery practices. In his session at DevOps Summit, Martin Krienke, Sr Development Manager at T-Mobile, will discuss where they started their Continuous Delivery journey, where they are today, and where they are going in an effort ...
SYS-CON Events announced today that the "First Containers & Microservices Conference" will take place June 9-11, 2015, at the Javits Center in New York City. The “Second Containers & Microservices Conference” will take place November 3-5, 2015, at Santa Clara Convention Center, Santa Clara, CA. Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities.
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...
Buzzword alert: Microservices and IoT at a DevOps conference? What could possibly go wrong? In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, the leading expert on architecting agility for the enterprise and president of Intellyx, panelists 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 our distributed cloud en...