Mock Server Starter Kit

Number of APIs: 6

Getting Started

Using mock servers is a great way to use Qodex to build an API as part of your API-First mindset. API-First is a way to define, design, document, and test your API experience before you develop any software for the API itself. We will focus on REST and GraphQL today.

This workshop will get you started with some of the basics of building an API by exploring different endpoints and saving responses to create a mock server. This mock server, then, can be used to write behavior-driven testing for your desired user-experience.

This workshop will be use a different server for each of the API types. The REST design will use the Qodex echo server which responds with payloads of data in an echo response of what you send to it. The GraphQL design will use a Spotify music search.

At a high level, you'll add requests for these API types, save responses as examples, and then turn those examples into a mock server for your development environment.

Fork This Collection into a Workspace

You will need to be logged into your Qodex account to continue.

If you haven't created a new workspace, you can click on Workspaces at the top of the application and click on the Create Workspace button. Give your workspace a name which is unique to your account. Give it a summary explaining what it is for, and set the Visibility of the workspace to Personal for now.

Next, make sure you're back on the [Mock Server Starter Kit] Click on the three dots next to this collection's name and choose Create a fork. Set a label for your forked copy. You will need to provide a workspace where you'd like to copy this collection. Your newest workspace should be at/near the top of this list. Click the Fork Collection button.

You should be on your own workspace now with a successful fork of the Mock Server Starter Kit collection.

Next, click on the Environments icon on the left side of the Qodex application and click the Plus Sign (+) to create a new environment in Qodex. Call this Development.

Add a variable called echoURL and set its INITIAL VALUE to https://Qodex-echo.com When you click on the CURRENT VALUE field, Qodex should also populate the CURRENT VALUE for you. Save your changes. This URL will be used for our REST API.

Add another variable called spotifyURL and set its INITIAL VALUE to https://Qodex-spotify-graphql.herokuapp.com When you click on the CURRENT VALUE field, Qodex should also populate the CURRENT VALUE for you. Save your changes. This URL will be used for our GraphQL API.

Next Steps

From here, the instructions will be mentioned at a very high level to apply to all API types for which there are folders in this collection.

If you want more specific instructions based on the type of API you intend to build, refer to that folder within the Mock Server Starter Kit collection. Each folder will have its own documentation with more specific instructions. When you click on the folder name, you should see more specific step-by-step instructions.

Step One - Run requests and save their responses

Choose your new environment from the top right corner of the application so the appropriate request URL variables will resolve properly for your API type.

From your API choice, you're going to select a request, send the request, and save a response. Exact instructions will vary for the API type and you can view this in more detail in their respective folder's documentation.

If you try to send a request and see an error like Couldn't resolve host then your environment is not set properly, or the variable you added to your environment wasn't set or saved properly. The environment variables are case-sensitive, so be sure they are entered correctly.

Step Two - Edit the Responses

Saved responses are useful for offline work, and Qodex will also use them for creating a mock server.

Mock servers in Qodex will look for matches of URL, HTTP method, and parameters, and send back what it feels is the best response. Mock servers echo back the responses you save for these conditions.

For RESTful APIs, this is a quick process, but GraphQL queries will take two extra steps. Check the GraphQL folder's documentation for these details.

Be sure to also add saved responses that cover potential error conditions as well, like 400-series and 500-series errors so that you can also develop a good user experience in as many cases as possible.

Step Three - Create a Mock Server

Click on the '...' three dots next to the Mock Server Starter Kit collection name, and select Mock collection from the list.

Give the mock server a unique name within your workspace, choose your Development environment in the appropriate dropdown, and click Create Mock Server at the bottom of the interface.

Creating a mock server will also create a new environment with the same name you gave your mock server. We recommend changing the environment name to Mock Server so it's less confusing later. Also, your mock server's environment has its URL stored in a variable called url. You should also make a variable called echoURL and spotifyURL that are set to the same mock server URL.

Your mock server is now built and will respond to your examples. You can test this with Qodex by selecting your mock server's environment in the top right corner of the Qodex interface and calling your requests. How to test this may vary based on your API type, so check the appropriate folder documentation.

Any examples that you add/edit/delete will update your Mock Server automatically!

If you want to add/edit/delete an endpoint, you can simply add more saved responses, change their status codes and response bodies, etc, and your mock server will update automatically. (it might take a few moments to sync)

---

Instructions from this point are the same for all of the APIs.

Step Four - Create Documentation

Creating client-facing API documentation is a single-step process.

Click on the Mock Server Start Kit collection.

If the documentation panel doesn't automatically open, click on the page icon at the right edge of the application to expand that panel, and click View complete collection documentation at the bottom of that panel.

The documentation is automatically generated and updated with every change you make to your requests and saved responses.

You can use the Publish icon at the top right corner if you want your documentation to be available for everyone to see.

Code Generation

The documentation that was generated for you also includes code samples in a variety of languages and libraries such as JavaScript - Fetch or Ruby - Net::HTTP.

You can select a single saved example response, and click the code icon () on the right edge of the screen and select your favorite programming language from the list to see some sample code.

More about Environments

Once you decide on whether you're going to use REST or GraphQL, you can remove whichever variable you no longer need from your Development environment. We also recommend changing the variable name to something like baseURL but you'll need to change each of your requests and examples to use this new variable name.

Once your team has the real API created, you can make a Production environment and set your baseURL to be your public URL to test your code via Qodex.

Now, testing your code in development mode or production mode is as easy as swapping your environment in the top right corner of the Qodex interface.

What's Next???

We recommend that once your Production environment is working, to publish documentation using your Production environment. This will also generate a great Run In Qodex button which will allow others to interact with your APIs! You can copy the Run In Qodex button into your project README files as well if you are open-sourcing your work on sites like GitHub.

Someone Call Security!!

PLEASE be careful with API keys in your public-facing workspaces. NEVER set a real API key as an INITIAL value in your environments or it will be available to everyone in the world, even if you set the variable type to secret. Anything you ever store as secret should ONLY be set as a CURRENT value, which will save in your local application environment.

1. RESTful endpoints - sample PUT request PUT {{echoURL}}/put

2. RESTful endpoints - sample GET request GET {{echoURL}}/get?param1=value1

3. RESTful endpoints - sample POST request POST {{echoURL}}/post

4. RESTful endpoints - sample PATCH request PATCH {{echoURL}}/patch

5. RESTful endpoints - sample DELETE request DELETE {{echoURL}}/delete

6. GraphQL endpoints - artist lookup POST {{spotifyURL}}/graphql