JSON API Phase 1: Setup

Setting up your projects

Welcome! Today you begin an adventure and you shall embark on a journey that will bring you fame and glory. You shall build an API server and a client app that shall wield its power! Are you excited?

🦗🦗🦗

Alright then, lets assume that silence is because you are speechless and waiting in anticipation.
Lets go!

Introduction

For the API, we'll be defining our schema with the Swagger (OpenAPI) specification, conforming to the JSON API specification, and implementing it all with an express server. Once that is all in place, we'll create an Ember app and utilize its JSONAPIAdapter to effortlessly integrate with the API. Furthermore, Ember Data uses the JSONAPIAdapter by default.

NOTE: For this tutorial series, we will be utilizing Swagger 2.0 specification. The OpenAPI 3.0 specification was released last year (2017), but there are currently only a limited number of implementation resources. You will find a wealth of knowledge and implementations which use the 2.0 spec. Nonetheless, I definitely encourage you to read up on version 3.0.

Ember Project

In a moment, your ember client app should be up and running. Feel free to follow Ember's quick start if you'd like to learn more. Otherwise, if you load the web page now, it should look like this:

API Server

Next we'll be using the swagger CLI tool to configure the API server project. The swagger CLI adds express-swagger-mw to your project. This package contains an express middleware wrapper around swagger-node-runner. swagger-node-runner is a swagger server implementation that uses bagpipes and sway. If your project has more complicated requirements, you'll want to dig into the documentation for these projects. For our use case, these swagger internals will just work out of the box.

If you haven't yet, use CTRL+C to stop the ember server, and enter the following commands:

cd ..
swagger project create api

The CLI should immediately prompt you to select a framework.
For this demo, select express:

? Framework?
connect
❯ express
hapi
restify
sails

Then cd into the directory:

cd api

Run the server

swagger project start

Then, in another terminal window, use the command below to test with curl: