Import WSDL for an Existing SOAP Web Service

Modern APIs and microservices is primarily delivered as RESTful, RPC, and GraphQL APIs using HTTP, but as the result of the widespread adoption of services oriented architecture (SOA) in the early 2000s, there are still many web services in production. SOAP is rarely used to deliver new APIs, but because of the ubiquitous nature of the approach within long living enterprise infrastructure, SOAP web services continue to play a significant role as part of API operations. This lifecycle blueprint acknowledges that existing SOAP web services have a place in the modern enterprise, and can benefit from some of the other healthy elements present across the API lifecycle for other types of APIs and microservices, ensuring they are well documented, have testing in place, as well as being monitored and discoverable just like the rest of API operations. This blueprint provides one possible path to consider as teams look to modernize their API infrastructure.

Define

For traditional web services the web services description language (WSDL) is the key to defining and understanding what each API is capable of. Similar to an OpenAPI, the WSDL describes the surface area of a SOAP web service, defining the available methods and payload structure. Upon import or creation of a new API using WSDL, a modern API lifecycle can be set into motion through the generation of collections for documenting and testing of web services. Helping modernize existing web services by applying some of the common elements of modern API lifecycle to existing WSDL services.

Team Workspace

Any API you are looking to develop should have a known location where any stakeholder can get up to speed on what is happening with the development and operation of an API. Postman team workspaces provide a single location to publish APIs, documentation, mock servers, tests, and other artifacts, providing a known location that is discoverable across teams. Establishing early on a place for teams to engage around the design, development, and operation of an API, that makes the API lifecycle observable by default. Team workspaces are only accessible internally to your team members who have an account under your designated organizational Postman team, making it available across search, and via workspace browsing for your team to discover and begin collaborating and working across APIs being developed within each workspace.

Team Members

Once a team or public workspace has been established for an API, or group of APIs, it is time to define and invite all relevant team members to the workspace. Sitting down to make sure your team is well defined and invited to your workspace and repositories allows you to think through who is involved, what roles they have in moving an API forward, and is something you can revisit on a regular basis. It is also something that allows others to easily see who is involved with an API, and who they can reach out to with questions or feedback through the life of an API.

WSDL

The Web Services Description Language (WSDL) is an XML-based interface description language that is used for describing the functionality offered by a web service. The acronym is also used for any specific WSDL description of a web service, which provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. Therefore, its purpose is roughly similar to that of a type signature in a programming language. A WSDL can be imported or created from scratch to kick-off an API lifecycle, using the web service definition to generate documentation, mock servers, or tests, allowing legacy SOAP web services to managed as part of a more modern API lifecycle, bringing it up to par with other more modern microservices and APIs when it comes to elements of their operation.

Document

Having complete, accurate, and easy to follow documentation is essential for all APIs, and is something that alleviates the number one pain point for API consumers when it comes to onboarding with any API, expanding the number of API paths an application puts to work. Modern approaches to producing API documentation have moved beyond a single static version of documentation simply published to a portal, as well as there being potentially multiple forms of documentation for any single API. Helping API producers onboard consumers easier, reduce the cognitive load when understanding what an API does, and properly define specific business use cases of an API being put to work in an application or as part of an integration.

Reference Documentation

The most common form of API documentation is what can be described as reference documentation, providing a complete “menu” of all paths available for an API, along with all the parameters, headers, body, and examples to put to use. Ideally reference documentation is logically organized using folders and tags, and provides informative and useful summaries and descriptions for every individual path. Every API should have up to date and informative reference documentation that allows API consumers to understand the entire scope of an API, but also find exactly the path or paths they need to use as part of their application or integration. Reference documentation for all APIs is an essential part of a healthy API lifecycle, but teams should also be considering what other forms of documentation would help new users, specific domains, as well as describing some of the most common workflows an API is used for when it comes to desired business outcomes.

Test

A test-driven API lifecycle ensures that each API delivers the intended outcomes it was developed for in the first place, providing manual as well as automated ways to ensure an API hasn't changed unexpectedly and is as performant as required, helping establish a high quality of service consistently across all APIs. API testing should not be an afterthought and should be a default aspect of the API lifecycle for any API being put into production. API testing takes a solid investment in establishing proper testing practices across teams, but once you do the work to establish a baseline of testing, properly train teams on the process and tooling involved, the investment will pay off down the road.

Contract Testing

Contract testing ensures that each individual API and collection paths comply with the contract that was put forth for each individual version of an API. OpenAPI for each API can be used to generate collections providing 100% coverage for all of the API paths present. JSON Schema provides the details of the contract, and when applied as part of an OpenAPI definition, you end up with a machine readable contract that can be manually or automatically tested against. It is common for collections to be defined for the contract tests of each API, and then have these contracts tests scheduled for regular run via a monitor, as well as included as part of CI/CD pipelines, providing robust coverage for contract tests that developers can manually execute, or automated as required as part of the API lifecycle.

Performance Testing

Performance testing establishes a benchmark for what can be expected when it comes to the response time for each API. The OpenAPI for each API can be used to generate collections that provide 100% coverage for all of the API paths present, or performance tests can be applied to just a subset of API paths. It makes sense to have performance test collections separate from other types of testing so that they can be run independently from contract, integration, or other types of tests. Helping establish that the performance levels are met from potentially different regions that reflect actual application usage of APIs. Providing a comprehensive look at the performance of an API from across multiple regions for 100%, or a sensible sampling of API paths, ensuring that APIs and the teams behind them are meeting their SLAs over time and across the entire API lifecycle.

Secure

Security must be its own area of the API lifecycle, but it is something that should span testing, authentication, and potentially other areas of the API lifecycle. Over the last five years the world of API security has expanded, while also moving further left in the API lifecycle as part of a devops shift in how APIs are delivered. There are a number of elements present when it comes to security, but depending on the overall maturity of API operations the available resources and prioritization available to adequately realize these elements vary.

Authentication

Authentication begins on the producer side by selecting the appropriate authentication method when deploying an API to the gateway, setting the tone for how identity, authentication, and access control will work across the API lifecycle. Next, authentication can be defined as part of API consumption at the collection, folder, or individual request level, providing a configurable authentication layer for automating across API operations. Authentication should be balanced across both the producer and consumer side of the API lifecycle, putting well-known practices to work, allowing both sides to securely access, refresh, and engage with necessary authentication.

Security Testing

Security testing ensures that 100% of the surface area of an API is secure against the common types of attacks as defined by OWASP. The OpenAPI for each API can be used to generate collections that provide 100% test coverage for all API paths, ensuring that every API, and detail of the API is evaluated as part of common security practices. No API should move into production without having a security collection defined for testing for all of the known vulnerabilities, moving the security conversation further left in the API lifecycle–allowing developers to manually test as they develop an API, but then also allowing for the automation of API security testing as part of the deployment pipeline, or scheduled via a monitor. Security testing is just one part of a larger testing, but also security strategy, helping standardize how security is applied, while also properly equipping teams with the latest information and practices they need to be successful in securing API operations.

Monitor

Monitors can be used to execute any Postman collection applied to any environment. Due to the versatility of what a Postman collection can define, collections turn monitors into a powerful API automation and orchestration tool. Beginning with the ability to schedule contract, performance, and other types of tests, but then also allowing for automating specific workflows across many different APIs. Since collections can be used to define anything that can be defined via an API, monitors can be used to schedule the running of each capability from multiple cloud regions, applying many different environmental variables. Making monitors an essential, versatile, and executable part of defining how the API lifecycle works.

Contract Testing Monitor

Monitors can be used to automate the scheduling of any contract test, taking any collection of API requests, complete with test scripts, combined with a targeted environment, and run in a variety of cloud regions on a recurring schedule. Providing the ability to independently execute the contract testing for each API, but then monitor the contract testing of each API over time to make sure nothing has changed. Providing the essential automation of contract testing needed to ensure it is consistently applied across all APIs, defining whether or not an API is not just meeting the uptime portion of its service level agreement, but actually is meeting business needs in an ongoing way.

Performance Testing Monitor

Monitors can be used to automate the scheduling of any performance test, taking a single, or a variety of API paths and making sure they meet the established baseline for response time. Monitors take your performance testing collections and allow for their execution on a recurring schedule, from any cloud region, with a specific set of environment variables applied at execution time. It is important that performance testing exist as their own collections so that performance testing monitors can become more precise in where and when they run, providing a robust look at API performance from the regions and times of day that matter the most. Performance testing monitors are essential in realizing a certain quality of service at scale across all APIs in production, providing an executable unit for understanding the performance of all API resources and capabilities over time.

Security Testing Monitor

Monitors can be used to automate the scheduling of any security test, taking collections that are generated from an OpenAPI and scanning every path for potential vulnerabilities. Collections provide the definition of the surface area of the API and test scripts provide the ability to automate security testing against each individual path, which is something that when combined with a specific environment, and then schedule to run as a monitor becomes a very robust way to scale security testing across the surface area all APIs.. Allowing any developer to add security testing to the stack of contract, performance, and other testing, but then also contributing to the overall security strategy applied across API operations, meeting the needs of individual APIs, but automating security in a way that prevents any API from falling behind, and becoming the next breach we’ll read about in the news.

Discover

The ability to discover APIs at all stages of the API lifecycle is essential for reducing redundancy across operations, helping teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs, while supporting documentation, relevant workflows, and the feedback loops that exist as part of the operation of APIs internally within the enterprise, or externally with 3rd party developers. API discovery does not live at the beginning or the end of the API lifecycle, but should be considered across all areas of the API lifecycle, ensuring that APIs, as well as the operations around them are as discoverable as possible, but well informed when it comes to privacy, security, and terms of service.

Search

Search is the fundamental element of API discovery, allowing API producers to search for existing APIs before they begin the development of new APIs, as well as API consumers to search for APIs they can use as part of their applications and integrations. A healthy API lifecycle depends on the ability to search internally and externally for APIs, as well as the operations around them. The indexing of workspaces, APIs, and the elements of the API lifecycle like documentation, mock servers, and tests should occur by default across all teams before the desired efficiency and velocity will be realized across operations. Postman platform search provides visibility across these dimensions of API operations, looking across private, partner, and public dimensions, but then also leverages a role based approach to what elements of API operations are surfaced based upon your role–making API search a priority as part of the API lifecycle.

Private Network

A private network is available for any team as part of the Postman platform. The private team network is accessible via the home page and provides a place to publish APIs, and each version of an API so they can be discovered by internal consumers. APIs can be added to the private network from the network itself, as well as part of managing the API within any workspace where the API is being managed. APIs in the private network will show up in the wider search, and allow for grouping and browsing by folder. Enabling teams who are producing APIs to easily increase the visibility of their APIs across teams, and beyond the workspaces where they are being developed. Increasing the chance that other teams will find before they begin developing a potentially duplicate API, or be able to put it to use within the application or integration they have planned.

Conclusion

This blueprint intends to provide a high level walk through of one possible way of defining a standardized API lifecycle which is centered around an existing SOAP web service. Each element within this blueprint works to provide a simple overview of what is involved across the entire life of an API, with more detail present on the detail page for each element (if you are viewing this on the API lifecycle project site). If you are reading this via a PDF or printed version you can visit the landing page for this blueprint to access more information and view specific actions you might possibly consider taking as part of applying each element of this proposed lifecycle within your own operations. This blueprint is a living document and will continue to evolve and be added to over time based upon feedback from readers. If you have any questions, feedback, or feel like there is more information you need, feel free to jump on the Github discussion for this blueprint, or any of the individual elements present--the value this blueprint provides is actively defined by the feedback community members like you.