Generating OpenAPI or Swagger From Code is an Anti-Pattern, and Here’s Why

(This article was originally posted on Medium.)

I’ve been using Swagger/OpenAPI for a few years now, and RAML before that. I’m a big fan of these “API documentation” tools because they provide a number of additional benefits beyond simply being able to generate nice-looking documentation for customers and keep client-side and server-side development teams on the same page. However, many projects fail to fully realize the potential of OpenAPI because they approach it the way they approach Javadoc or JSDoc: they add it to their code, instead of using it as an API design tool.

Here are five reasons why generating OpenAPI specifications from code is a bad idea.

You wind up with a poorer API design when you fail to design your API.

You do actually design your API, right? It seems pretty obvious, but in order to produce a high-quality API, you need to put in some up-front design work before you start writing code. If you don’t know what data objects your application will need or how you do and don’t want to allow API consumers to manipulate those objects, you can’t produce a quality API design.

OpenAPI gives you a lightweight, easy to understand way to describe what those objects are at a high level and what the relationships are between those objects without getting bogged down in the details of how they’ll be represented in a database. Separating your API object definitions from the back-end code that implements them also helps you break another anti-pattern: deriving your API object model from your database object model. Similarly, it helps you to “think in REST” by separating the semantics of invoking the API from the operations themselves. For example, a user (noun) can’t log in (verb), because the “log in” verb doesn’t exist in REST — you’d create (POST) a session resource instead. In this case, limiting the vocabulary you have to work with results in a better design.

It takes longer to get development teams moving when you start with code.

It’s simply quicker to rough out an API by writing OpenAPI YAML than it is to start creating and annotating Java classes or writing and decorating Express stubs. All it takes to generate basic sample data out of an OpenAPI-generated API is to fill out the example property for each field. Code generators are available for just about every mainstream client and server-side development platform you can think of, and you can easily integrate those generators into your build workflow or CI pipeline. You can have skeleton codebases for both your client and server-side plus sample data with little more than a properly configured CI pipeline and a YAML file.

You’ll wind up reworking the API more often when you start with code.

This is really a side-effect of #1, above. If your API grows organically from your implementation, you’re going to eventually hit a point where you want to reorganize things to make the API easier to use. Is it possible to have enough discipline to avoid this pitfall? Maybe, but I haven’t seen it in the wild.

It’s harder to rework your API design when you find a problem with it.

If you want to move things around in a code-first API, you have to go into your code, find all of the affected paths or objects, and rework them individually. Then test. If you’re good, lucky, or your API is small enough, maybe that’s not a huge amount of work or risk. If you’re at this point at all, though, it’s likely that you’ve got some spaghetti on your hands that you need to straighten out. If you started with OpenAPI, you simply update your paths and objects in the YAML file and re-generate the API. As long as your tags and operation Ids have remained consistent, and you’ve used some mechanism to separate hand-written code from generated code, all you’re left to change is business logic and the mapping of the API’s object model to its representation in the database.

The bigger your team, the more single-threaded your API development workflow becomes.

In larger teams building in mixed development environments, it’s likely you have people who specialize in client-side versus server-side development. So, what happens when you need to add to or change your API? Well, typically your server-side developer makes the changes to the API before handing it off to the client-side developer to build against. Or, you exchange a few emails, each developer goes off to do his own thing, and you hope that when everyone’s done that the client implementation matches up with the server implementation. In a setting where the team reviews the proposed changes to the API before moving forward with implementation, you’re in a situation where code you write might be thrown away if the team decides to go in a different direction than the developer proposed.

It’s easy to avoid this if you start with the OpenAPI definition. It’s faster to sketch out the changes and easier for the rest of the team to review. They can read the YAML, or they can read HTML-formatted documentation generated from the YAML. If changes need to be made, they can be made quickly without throwing away any code. Finally, any developer can make changes to the design. You don’t have to know the server-side implementation language to contribute to the API. Once approved, your CI pipeline or build process will generate stubs and mock data so that everyone can get started on their piece of the implementation right away.

The quality of your generated documentation is worse.

Developers are lazy documenters. We just are. If it doesn’t make the code run, we don’t want to do it. That leads us to omit or skimp on documentation, skip the example values, and generally speaking weasel out of work that seems unimportant, but really isn’t. Writing OpenAPI YAML is just less work than decorating code with annotations that don’t contribute to its function.

Why Everyone Should Invest In An ITSM Tool

[et_pb_section][et_pb_row][et_pb_column type=”4_4″][et_pb_text admin_label=”Text”]
We’ve all heard the question before: “Should we invest in an IT Service Management Tool?”
The simple answer is yes. There’s really no counterpoint. Small, midmarket and enterprise organizations will benefit greatly from purchasing and then leveraging an IT Service Management Tool (ITSM) tool.
What Is IT Service Management (ITSM)?
At a high level, ITSM is the backbone of your IT organization. It’s the teams, groups and departments that handle the front-facing communication and support of your IT organization. They’re the ones that receive support requests and provide them to your backend teams, developers, etc. Think about them as the face of your IT organization. They need a management tool to do their jobs effectively.
What An ITSM Tool Can Do For You
There are many ITSM tools out there such as HP Service Manager, Remedy, Service Now, IBM Control Desk, C2 Atom and many more. Each offers its own user interface and reporting structure. Some have additional add-on tools and features or different levels of packages to support your unique needs. No matter the tool you select, the majority will at minimum come with a configuration management database (CMDB) as the backend database for your tool, as well as a basic ticketing system. Both of those tools are critical to the business, so you’re already winning, because your requests and your assets are being tracked in one tool. You can easily escalate and assign tickets for support or enhancements and do some basic reporting as well as track your assets. At a minimum you’ve just saved time and resources by streamlining your ticketing process.
Is that enough to write a use case and convince your company to look at investing in an ITSM tool. Maybe not. But it’s doesn’t stop there. We all know that IT changes, software changes and upgrades need to be put in, and service managers need to track these changes and/or obtain approval. We also need to make sure we’ve properly documented backout plans to ensure there are no conflicting changes happening during the same window. An ITSM Tool can do this for you. The change-management system in most ITSM Tools can automate your change-request process with enhanced questions that can assess the risk of the change and send automatic approval notifications to impacted parties utilizing your flashy new CMDB to get information on who owns the system or utilizes the system and who may be impacted by the change.
What’s so great is that it saves your change information and backout plans for future reference and knowledge sharing. Some even have an integrated change calendar that will show you any overlapping changes or maintenance windows that may impact your change. You’ll also be able to relate a change record to an incident ticket if additional support is needed during the change or if the change causes an outage. This is a more effective way to track any trending or knowledge needed for future changes.
Most ITSM tools also offer a knowledge base as on out-of-the-box option, because knowledge sharing and transfer is key to successful service management. The ability for a developer or network engineer to provide relevant information back to the service desk in a searchable format can increase your first-call resolutions (FCRs), or the time it takes to identify how to escalate an issue. The knowledge base can also be utilized to share knowledge to your user community with basic troubleshooting or automated support for frequently asked questions, issues or known issues with workarounds. This will in turn reduce the numbers or reoccurring calls to your service desk for issues that can be easily resolved by the user, and will free up your service desk analysts to handle more technical requests.
The above-mentioned features – CMDB, ticketing tool and knowledge base – are your basic features of an ITSM Tool. But there are other out-of-the-box functions, plus additional add-ons you can purchase to serve other business needs. These can include trending analysis, reporting/metrics, software-asset management, hardware-asset management, project-portfolio management, event-management integration, self-service portal, automated workflows, SMS escalations or phone-calling tree automation, and application-programming interfaces (APIs) that integrate with other systems to read from or write to the ITSM tool.
Why Do We Need An ITSM Tool?
Look at your IT organization and think for a moment of the services you provide. You most likely have some sort of request process for the service desk via email, phone, instant message or even web requests.
How do the service agents handle these requests? How do they document and resolve these requests? What happens if the request needs to be escalated?
The process you have in place probably works as requests are handled, problems get resolved and that guy on the 3rd floor who wanted a new laptop eventually got one. So why would you need an ITSM tool if everything is great and it works? Don’t fix it unless it’s broken, right? Wrong.
Even if your process seems like it’s working, is it really? Are you tracking changes? Can you easily provide trending analysis on common issues? Do you have a CMDB that stores your people, processes, assets and the lifecycle for them? Are your requests being escalated and turned around in an acceptable service level agreement (SLA)? How are work efforts prioritized? What happens when an outage occurs? Are teams notified? Is the outage documented and follow up on? How many different systems/applications are you utilizing to ensure these efforts happen? How much time, effort, support and money are you spending on these systems/applications to provide the basic functionality of requesting IT services?
Investing in an ITSM Tool will almost pay for itself simply by reducing the cost associated with support, time, resources and reoccurring outages. It’ll enable you to streamline your support process and even automate some of your manual tasks, like tracking, metrics reporting, and communicating about the services you provide to the organization.
Purchasing An ITSM Tool Vs. Building An In-House Tool
Let’s say you decide that an ITSM tool will absolutely help your organization. The purchasing cost is now under review, but you have a team of developers on the payroll that might have some availability to take on a project and produce an in-house ITSM solution. Here are some of the pros and cons to consider before building the tool in-house.
Pros:

  • Everything’s done in-house
  • You don’t need to spend any money up front to acquire a product
  • There’s no licensing
  • Your dev team knows how to support it
  • It’s customized to your specific needs

Cons:

  • Your developers are being paid to work on this project when they could be doing other production development
  • As your environment changes, your in-house solution will need to be updated, which will eat up more development time
  • If your solution is web-based and browsers, scripts and other plugins are updated, it may not work as intended and require more development
  • Knowledge transfer of the tool and how it was developed needs to be documented. If your developer leaves, the next developer must be able to support or upgrade the app
  • You may need to write code to integrate other applications such as email or phone into your app. As those systems are upgraded, the code may need to be revised
  • Requirements for the app may change as the organization matures or grows, which will consume additional development time
  • If and when the app reaches the end of its lifecycle, there’s no support or upgrade options readily available
  • There’s no CMDB, unless your team plans on developing one
  • The system of record will not be easily transferrable to another system of record if needed in the future

These are high-level pros and cons, but each organization will have more specific and customized lists depending on the functionality and requirements needed. Given all the cons, why not let someone else who’s already invested time and resources do the work for you? The tools out there are robust, and some are open for additional customization or in-house development to fit your specific needs. There are also additional support options for these tools to assist your organization when issues arise or during implementation.
Don’t waste your resources or time trying to reinvent the wheel when someone’s already invented one and enhanced it.
Original image by Max Max
 
[/et_pb_text][/et_pb_column][/et_pb_row][/et_pb_section]

API Management Enables Dynamic Systems of Engagement

When I first heard the term API Management, my mind went back to the mid 1990’s when I was neck deep in object-oriented programming.   Ugh, I remembered combing through reams of documentation about application programming interfaces, object structures and the like. It wasn’t necessarily the fun part of developing applications. Back then, the context was connecting core application systems together, exchanging transactional and master data between applications such as CRM, ERP, and Supply Chain.

Nowadays many of the underlying technical details remain relevant, but the context has changed from API’s as a systems development concern to API management as a business model consideration and key topic in the board room. With innovation and speed to market as primary concerns among executive ranks, key enablers such as API Management solutions are getting due attention to help unlock the creative potential of next-gen application developers, both internally and externally, and to even develop new revenue streams.

From an external perspective, API management solutions can provide a welcoming experience for customers, business partners, and communities. Hackathons have exemplified the notion of turning loose a group of talented individuals to bring a fresh perspective on how core IT assets can be turned into something new and useful in ways that perhaps would have never been conceived internally. These new systems of engagement need to plug into core IT assets in a way that is securely controlled and measured, yet easy to access and understand in a self-service approach. Done well, API management provides the virtual welcome center for a self-guided tour.

From more of an internal approach, one of the trends that reinforces the need for API management is the growing tension between line-of-business and IT, which is typified by LOB-lead projects that attempt to minimize dependencies on the core IT organization. This has been described by industry analysts, such as Gartner, as the emergence of Bimodal IT where the business intends to drive more dynamic systems of engagement that give them some degree of freedom from the back-end systems of record that are heavy and slow to change. In this case, API management serves as the clean hand-off point that can help streamline the relationship between LOB-lead projects and core IT.

As with most any technology solution, realizing effective API management requires careful planning and perhaps some non-traditional IT skills. The rendering of IT services as API’s is not necessarily the hard part. Defining internal and external-facing processes to manage the lifecycle of API usage will be an important factor in the long term value proposition. What’s more, solid technical writing skills can be crucial to making or breaking the developers’ experience as they discover and embrace the IT assets that are made available. Nonetheless, a simplified pilot can be an effective entry point to get started on the journey.
TxMQ works with companies of all sizes and shapes to harness the potential of the digital economy. Get in touch today for information on how we can partner with you on your digital evolution.
(Image by opensource.com)
 
 

How Do You Support Your Software?

Software/OS services & support not your core competencies? We support more than just WebSphere.

In today’s reality of constantly evolving technology, managing software support is critically important. There are never-ending changes to core products, changes to deployment options (on-premises, cloud, hybrid), and a new generation of changes is most certainly lurking around the corner. Especially in IBM’s Systems Middleware world.

The effort to support this endless hodgepodge has grown increasingly complicated. In point of fact, most companies run multiple versions of software on different operating systems, which makes support options even more confusing. That’s why more and more companies are facing hard decisions about whether to continue their vendor-support agreements for software and OS, and why more and more companies are running unsupported software and OS, even if it’s occasionally side-by-side with a newer, supported version of the same.

That’s why more and more companies are partnering with TxMQ for support of their IBM environments, WebSphere systems and far more.

TxMQ is uniquely able to design and deploy support solutions across almost any software/OS environment. And we’ll design a solution that fits right – whether it’s short-term support until the patch/upgrade is finished, or long-term permanent outsource options and partnerships. All options are available 24/7/365.
In addition, we’re one of the few firms that supports legacy mainframe, systems I and P (aix), alongside Linux (all major flavors), Solaris, Windows and other variants. So yes, we’re a lot more than just pure IBM.
A few other notes about our capabilities…

Additional Offerings
TxMQ support customers can also take advantage of reduced rates for TxMQ services, discounted purchasing of IBM software and hardware, and related services like software asset management (ILMT, SUA, SCCD), patch management and other managed services.

Implementation Support
TxMQ’s deeply technical talent can also help with planning for upgrades, replatforming, license optimization and integration services. In select cases, we can also work with in-house development teams to offer support for custom home-built applications.

Custom Solutions
TxMQ engineers and developers can work for you, or with your teams, for custom-application development needs. As with the above services, customers under support agreements with TxMQ are entitled to these services at a discount.
Let’s start a conversation on the advantages of getting back to basics and focusing on your core competencies, then letting TxMQ worry about your support.
Email info@txmq.com or chuck@txmq.com for more information, or call 716-636-0070 x222.