Vapor is a server-side Swift framework. It enables the creation and delivery of API’s and web applications using the Swift language.

You might be asking “Why do server side with Swift? Surely we have lots of other languages we can use?”. Well, you are right. But consider this, what if you are a Swift developer that does not know Web languages like PHP, Ruby, JavaScript, or this week's fancy new web framework/language?

Guess what, you can just use those new Swift skills you have been working hard on learning instead.

Plus, using Vapor means you do not need a third party server like IIS or Apache to run the application. Vapor can deliver the application for you across the Web.

Time to start!

Check you have compatible versions of Xcode and Swift Installed

From the terminal, we will first run a script from the Web to ensure we have compatible versions of Xcode and Swift.

$curl -sL check.vapor.sh | bash

Install Vapor

Next, we want to install Vapor’s toolbox and Vapor, this might take a little while depending on your Internet connection. Again, we run a script from the terminal to make this install easy.

$curl -sL toolbox.vapor.sh | bash

Create a new Vapor project

Now that we have everything we need installed, it is time to create a Vapor application. Using the terminal we create a new application by giving it a name, this name will also be used as the folder name.

$vapor new hello-world
$cd hello-world

Create a new Xcode Vapor Project

You do not have to use Xcode if you prefer something else, for example, Sublime Text or AppCode. That said, I would recommend using Xcode to keep things simple. To use Xcode we need to create a project for Xcode to load because Vapor is not like creating a new Xcode project and selecting a template. So at the terminal simply type.

$vapor xcode

When creation is complete you will be asked if you want to open the Xcode project, if you do not say yes then stop reading now as you clearly do not intend to write code at this time!

OK, so project creation is complete. The next step depends on how you want to work with the application, I have included instructions for Xcode and from the terminal.

To build the new application in Xcode

Take note of the output after you created the Xcode project. It is telling us that we need to switch to the run scheme in Xcode.

When you Build and Run the application it will start a web server running on port 8080, you can view the application in a web browser using a local address, http://localhost:8080.

To build and run the application from the Terminal

I want to give you more than one way to work with Vapor, so please know that you are not restricted to using Xcode. You can take advantage of the Swift Package Manager, this means you can build and run from the terminal as well.

In the application directory, you can build from the terminal using

$vapor build

To run the application you will actually run the server using

$vapor run serve

The App

If we open up the web page we will not see much by default. But if we put http://localhost:8080/hello we should see a rather uninteresting JSON response saying

{"hello":"world"}

This means everything worked just fine! Time to move on and start writing some code.

The code that generated that return can be found in Sources>App>Routes>Routes.swift. Let’s take a look at that file as it will show us some of the basics we need to get started.

import Vapor

extension Droplet {
    func setupRoutes() throws {
        get("hello") { req in
            var json = JSON()
            try json.set("Hello", "World")
            return json
        }

        get("plaintext") { req in
            return "Hello, world!"
        }

        // response to requests to /info domain
        // with a description of the request
        get("info") { req in
            return req.description
        }

        get("description") { req in return req.description }

        try resource("posts", PostController.self)
    }
}

The main class in Vapor is called Droplet this is where you will do most if not all of the needed coding for your application.

Inside the extension is a function that handles routing for our application. If you are not familiar with that concept, it is a way to handle URL’s and serve up the right content. Let’s take a look at one to better explain how it works.

get("hello") { req in
var json = JSON()
try json.set("Hello", "World")
return json
}

When the URL http://localhost:8080/hello is entered in a Web browser, the application looks to see if there is code to handle a /hello request. In this case, it finds one and executes the code inside.

The code in this example creates a new JSON object and sets the contents to “hello” and “world”. The JSON object is then returned and delivered up in the Web browser.

If you were to enter http://localhost:8080/plaintext you get a different result. This time a simple string of “Hello, World!” is returned to the browser.

The Wrap

I hope that you are now comfortable installing and understanding the very basics of creating a Vapor application. As you can see, it is a lot simpler than it might first appear.

This gives us a solid base from which to start exploring and really creating more useful server-side applications that we can either serve up to users directly as web applications or as API’s for our applications to work with.