Before we build our first integration, let's get acquainted with the APIs we are going to use in this first service. As shown in the preceding diagram our inbound call is a SOAP request and therefore we need a WSDL definition which defines the inbound API. Our outbound call is a REST request to a service we host on apiary (https://apiary.io) and uses the API Blueprint standard (https://apiblueprint.org) to define the REST API.

Let's start with the inbound or source definition as shown in the following screenshot. The WSDL has one operation which uses an input, output, and a fault message:

The messages reference an XSD which defines the structure for our input, output, and fault message is as follows:

The WSDL is available in the downloads as ICSBook-Ch2-FlightAirlines-Source.WSDL.

As you can see the WSDL contains one synchronous operation called AllAirlines, which uses elements from the embedded XML schema for the input, output, and fault message. In Chapter 1,Introducing the Concepts and Terminology, we looked at a typical workflow, using this WSDL we eventually have to create mappings for the request, response, and fault flow. The request message contains two optional elements maxResults and startWith. Both elements control both the amount and which part of the set of airlines is returned. We can leave both elements from our request message in order to return the whole list.

The response message contains a list of airlines present in our backend, including their ICAO (International Civil Aviation Organization) code and call sign. The ICAO code is a location indicator used by air traffic control for flight planning. When an exception occurs, a WSDL fault is returned to the inbound caller, describing the fault. The backend API however, uses a different technology: Instead of SOAP it uses REST as its interface. Because REST is a software architectural style and not a hard defined standard, whereas SOAP binds directly to the use of a WSDL, there are multiple languages to define a REST API. The best known languages include RAML (http://raml.org), Swagger (http://swagger.io) and API Blueprint (https://apiblueprint.org). The latter two are supported by apiary, but we will use API Blueprint, because it is easier to understand. API Blueprint is a syntax to document an API in a concise yet expressive manner. We can easily design and prototype the APIs that we need to create or document. Additionally, we can test our prototype and even any already deployed APIs.

We define the data structure first and use the objects in our API endpoint. Doing this we decouple the elements of the API and enable modularity and the reuse of data. In this chapter, we are going to design and test our API first before using it in our integration. For example, we can model our data using the data description syntax used and reused in our API endpoints as follows:

# Data Structures 
 
## Airline (object) 
+ icao: UAL (string, required) 
+ name: United Airlines (string, required) 
+ callsign: UNITED (string) 
+ country: United States (string) 
 
# Airlines [/airlines] 
 
## Retrieve Chapters [GET] 
+ Response 200 (application/json) 
  + Attributes (array[Airline]) 

For the full API Blueprint specification you can find a well documented specification at: https://apiblueprint.org/documentation/specification.html.

The resulting JSON for which we are going to create the API for will look something like as follows:

{ 
  "Airline":[ 
    { 
      "icao": "KLM", 
      "name": "KLM", 
      "callsign": "KLM", 
      "country": "The Netherlands" 
    }, 
    { 
      "icao": "UAL", 
      "name": "United Airlines", 
      "callsign": "UNITED", 
      "country": "United States" 
    } 
  ] 
}