Got Swagger? How mapping your API helps to protect it.

What is a Web API?


A Web API or Application Programming Interface is a form of client-server interaction in which responses to requests return data in a machine-parseable format, as opposed to “rich” documents designed to render in client browsers such as HTML ‘webpages’.

Web APIs are almost exclusively served over HTTP, and typically return data in either XML or JSON formats. Interpreters and libraries for handling these data formats exist that allow the returned data to be parsed, and specific key/values to be addressed, such that they can be assigned to a variable. For example:

  "widget": {
    "window": {
      "name": "main_window",
      "width": 500,
      "height": 500

allows the window name to be addressed in a form similar to the pseudo-code example below, dependent on language used:

my parsedObject = JSON.parse(responseBody);
my windowName =;

Whereas a web application interface in a traditional web application might provide a user with a button that when clicked returns a new page from the server for the browser to render, an API call will typically return a “blob” of this machine-parseable data, which lends itself to processing computer code.


Why worry about API security?


API security is often barely mentioned. Web application developers are, broadly, aware of vulnerabilities such as the OWASP Top 10, but these barely or tangentially mention API security as of the latest (2017) update. [Although API security is now being acknowledged]

This may not have been an issue historically, however APIs are no longer a niche or secondary form of traffic. API calls now represent 83 percent of web traffic, according to a traffic review detailed in the Akamai State Of The Internet Security Report 2018. That figure may seem surprising to many, but it reflects the massive growth in API usage for client-initiated in-browser and in-app requests that massively out-scales the more traditional use of APIs for programmatic access to third-party services such as in Business to Business (B2B) back-end service communications.

The majority of API traffic is now in the service of custom web applications and mobile applications, itself the result of digital transformations and cloud-based application deployment. The web is changing rapidly and in this respect the OWASP Top 10 standard may have failed to keep up with this paradigmatic shift in the last few years. For many organisations, a central API gateway or loose collection of unrelated service APIs may now represent the organisation’s primary interface with customers and partners, and consequently present its primary attack surface and area of greater vulnerability.


Organisational API gateway


A study conducted by the University of Virginia researchers found out that API programmers, even after following the standard security practices, often deliver insecure code. They conducted research that determined that 67% to 86% of apps have security vulnerabilities that may be exploited by attackers.


Communicating with APIs


API traffic is generally based on solitary, atomic requests relating to specific data reads or writes. An example might be the request sent in with the parameters:


and the server response will be a JSON blob confirming only that the task was executed and the output status:

HTTP/1.1 200 OK
Date: Wed, 08 May 2019 11:26:05 GMT
Content-Type: application/json
Content-Length: 110
  "errors": null,
 "user_id": "123456",
  "success": true



HTTP-based RESTful APIs are those that conform to the Representational State Transfer (REST) model, meaning simply that they allow  requesting systems to access and manipulate textual representations of web resources by using a uniform and predefined set of stateless operations. Rest APIs are defined with a base URI, such as known as a root-endpoint. The root-endpoint is the starting point of the API and various methods will be populated in a hierarchical manner underneath this path.

However, unlike a web application, an API has no “homepage” containing hyperlinks to other resources or methods within the service and there is no guaranteed, native way of seeing all the methods available, or the arguments and authentication required for each. It may be possible to enumerate these by analysing the format of API calls made by authorised clients to which you have access or via returned error messages or imply blind/brute force enumeration.


Security Through Obscurity


Is the fact that an API is not “crawl-able” in order to build up a map of its extent, and hence attack surface, a good thing in terms of ensuring its security? Surely an attacker is inconvenienced by not being able to ascertain or determine all methods available and hence this makes it safer?

In fact, this is not typically the case and so-called “security through obscurity” is generally considered to be a security “anti-pattern” or bad practice. That is, if your system’s security relies only on the attacker not having knowledge of its design, then the system is considered to have an inherent weakness. This reliance on “security through obscurity” can produce resultant weaknesses if an attacker is able to reverse engineer the inner workings of the mechanism. Perhaps counter-intuitively, it is generally considered that security can best to obtained for a system when the specification is known, examined, open and tested.

In this article we’ll take a look at how a REST API can be documented using a Swagger file and look at the various reasons why exposing the inner workings of your API to all and sundry can in fact enhance its security.


Swagger Files


To understand what paths are available to you in an API, it is necessary – due to lack of “crawling” – to provide planned API consumers with some form of API documentation, an instruction manual that provides guidance on how to interact with the API. Because APIs are designed primarily for interaction with code rather than human interaction, the methods available are typically tightly defined and will not respond or operate correctly if valid input is not received in the expected format.

The OpenAPI Specification, originally known as the Swagger Specification is the predominant specification for producing machine-readable interface files – known as Swagger files – for describing, producing, consuming, and visualizing RESTful APIs. Typically the Swagger file may contain sections listing the methods available on the API and for each one enumerating:


  • The HTTP verbs (GET, POST, DELETE) supported;
  • the path that the method should be accessed at on the endpoint;
  • the expected request content type (e.g JSON);
  • the parameters expected and the type (e.g “string”) of each;
  • the security parameters for the method, including supported authentication methods such as bearer tokens; and
  • the proposed response object (headers and object) format in success and failure conditions.


A short snippet from an example Swagger file is shown below:

openapi: 3.0.0
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark]( or HTML.
  version: 0.1.9
  - url:
    description: Optional server description, e.g. Main (production) server
  - url:
    description: Optional server description, e.g. Internal staging server for testing
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
        '200':    # status code
          description: A JSON array of user names
                type: array
                  type: string

Critically, applications implemented based on OpenAPI interface files can generate documentation of all methods, parameters and models automatically or programmatically each time the underlying code is updated. This helps keep the documentation, client libraries, and source code in sync. However, as we’ll see in the next section, it also has important benefits for the security of the API.


How mapping APIs can help secure them


Consistency & Clarity

Sometimes an API may have both production and staging versions, with one instance containing an API function that does not exist on all versions of the target platform. This could cause portability problems or inconsistencies that allow denial of service or other attacks against the API. The use of inconsistent implementations can cause changes in behavior when the code is ported or built under a different environment than the programmer expects, which can lead to security problems in some cases.

Producing a Swagger file allows simple, even programmatic evaluation and assurance that methods presented are as expected and consistent, even across changing software release candidates.


Clarity of authentication requirements

A Swagger file contains a section explicitly outlining the authentication and security requirements for access, including authentication schemes supported, protocols used (e.g HTTP or HTTPS), and the scopes for access (e.g read, write or admin). This allows simple and unambiguous verification that an API is secured in line with expectations, and highlights immediately issues such as credential-based authentication being use on a plain-text (HTTP) endpoint, or write access being granted to a planned read-only endpoint. The security schemes can additionally be applied either across the API at a global level, or on discrete individual operations and methods.


Clarity of the data returned and data exposure

A swagger file also permits developers to review and ensure that an API method returns the appropriate data for each method, preventing information exposure and data leaks.


Obsolete functions

Without a Swagger file, it may not be clear what methods the API presents, or if deprecated methods have been properly removed and are no longer accessible in a given instance of the API. If the API presents deprecated or obsolete functions, an attack may be able to access functionality in an unauthorised or unplanned manner and compromise the security of the API


Auditing & Automated Analysis

Swagger files are written in JSON or YAML and so parsers exist for them at the machine-readable level. This permits Swagger files to be examined in an automated fashion, permitting the automated security auditing/scanning of API specifications and providing assurance that security schemas are properly applied etc.


Eyes On

Finally, an additional advantage of a Swagger file being produced for your API is simply that there are more eyes on the API, and more people – internal staff, code reviewers, consumers, external bug bounty hunters and security researchers – who can spot issues and report them to you for fix. This is a long-standing principle that is applied to Open-Source code bug-fixing in order to ensure its security.


How AppCheck can help

So how can AppCheck help you in securing your APIs?


Native API Scanning Intelligence & Swagger file support

AppCheck includes specific API scanning technology that is able to build up a map of a scanned both SOAP and REST API using WSDL and OpenAPI/Swagger file parsing, seeded targets and similar technologies, to ensure that the API is fully modelled and scanned.


API Authentication

AppCheck supports API authentication methods including API access keys to ensure that APIs can be authenticated against and all methods fully probed for vulnerabilities.


Custom Vulnerability Checks from First Principles

AppCheck includes API-specific vulnerability checks written by our in-house penetration testers, to detect previously unknown vulnerabilities from first principles.


Additional Information

As always, if you require any more information on this topic or want to see what unexpected vulnerabilities AppCheck can pick up in your website and applications then please get in contact with us:

Get started with Appcheck

No software to download or install.

Contact us or call us 0113 887 8380

Start your free trial

Your details
IP Addresses

Get in touch

Please enable JavaScript in your browser to complete this form.