diff --git a/content/tutorials/getting-started.md b/content/tutorials/getting-started.md index 91d03f43..c8408785 100644 --- a/content/tutorials/getting-started.md +++ b/content/tutorials/getting-started.md @@ -1,9 +1,9 @@ --- title: Create your first mock API with Mockoon -excerpt: Learn how to create your first mock REST API with Mockoon +excerpt: Learn how to create your first mock REST API with Mockoon in less than 5 minutes meta: title: Create your first mock API with Mockoon - description: Use Mockoon to create your first mock API server in no time and generate fake realistic JSON body for your frontends. + description: Use Mockoon to create your first mock API server in no time and generate fake realistic JSON data for your applications. image: tutorial-getting-started.png imageAlt: Mockoon logo in a rocket imageWidth: 1200 @@ -11,73 +11,89 @@ imageHeight: 400 order: 10 --- -Mockoon is a free cross-platform desktop application that takes API mocking to the next level. Mockoon offers a fast and easy-to-use interface and gives you complete control over your mock APIs with advanced functionality like [a templating system](docs:templating/overview), [a proxy mode](docs:server-configuration/proxy-mode), and [requests recording](docs:logging-and-recording/auto-mocking-and-recording). +Mockoon is a free cross-platform desktop application that takes API mocking to the next level. Mockoon offers a fast and easy-to-use interface and gives you complete control over your mock APIs with advanced functionality like [a templating system](docs:templating/overview), [a proxy mode](docs:server-configuration/proxy-mode), and [request recording](docs:logging-and-recording/auto-mocking-and-recording). -This tutorial will show you how to install the desktop mocking application and set up your first mock API. +This tutorial will show you how to install the desktop application and configure your first mock API. [![View the video version button{250x71}](/images/view-video-btn-250.png)](https://youtu.be/XKMCKwxMkWs) -> To learn more about APIs and API mocking in general, head over to our [API guide](/articles/api-guide-what-are-api/) or [API mocking guide](/articles/what-is-api-mocking/) +> 📘 To learn more about APIs and API mocking in general, head over to our [API guide](/articles/api-guide-what-are-api/) or [API mocking guide](/articles/what-is-api-mocking/) ## Step 1. Install the application -Mockoon is available on the three major operating systems: Windows, macOS, and Linux. Visit the [download section on the homepage](/download/) to download the binary or installer for your operating system: +Mockoon desktop binaries are available for the three major operating systems in various formats. It is also available in several stores like Windows Store or Ubuntu Snap. Visit the [download section on the homepage](/download/) to download the binary or installer for your operating system: -![Screenshot of the download section on the homepage {917x473}](/images/tutorials/getting-started/app-download-screenshot.png) +![Screenshot of the download section on the homepage{1373x374}](/images/tutorials/getting-started/desktop-application-download-screenshot.png) -After downloading the installer, double click on the file to install Mockoon and follow the instructions. Now, open the application to start setting up your first mock API. +Depending on the operating system, you will have to install the application by following the standard installation process, like double-clicking on the installer or dragging the application to the Applications folder. After the installation is complete, you can launch the application. ## Step 2. Create your first mock API -After launching the application for the first time, you will find a demo mock API, also called **"environment"** in Mockoon. You can keep it and build from here or create a new one. -To create a new mock API, click on the "New environment" button. You will be prompted to save the environment's JSON file: +After launching the application for the first time, you will have the opportunity to **take a quick tour of the interface**. You can skip this step if you are already familiar with the application or want to explore it by yourself. You can also access the tour later by clicking on the "Help" menu and selecting "Take the tour". -![Recording of creating a new environment{1171x754}](/images/tutorials/getting-started/create-mock-api.gif) +At the first launch, you will have a default setup, the **demo API**, also called an **environment** in Mockoon. This demo API showcases the main features of Mockoon and is a good starting point to understand how Mockoon works. -You can also rename the environment, as shown below: +You can keep this demo environment and build from here or create a new empty one, which we will do in this tutorial. -![Environment renaming{670x143}](/images/tutorials/getting-started/rename-environment.png) +To create a new mock API, click on the "New environment" button. You will be prompted to save the [environment's data file](docs:mockoon-data-files/data-storage-location) on your computer: -## Step 3. Create your first API route +![Recording of creating a new environment{1468x886}](/images/tutorials/getting-started/create-first-mock-api.gif) -The newly created mock API already includes a route on `/`. You can modify it by setting up the method and path of your choice. +> 💡 You can synchronize your setup in our cloud and collaborate with your coworkers by subscribing to [Mockoon Pro](/pro/) -You can also create a new endpoint by clicking on the blue "plus" button at the top of the endpoint list: +## Step 3. Create your first API endpoint -![Recording of adding a new API route{1171x754}](/images/tutorials/getting-started/create-api-route.gif) +The newly created mock API, or environment, already includes an endpoint with no path and a `GET` method. This endpoint will be available at `http://localhost:3000/` by default. You can modify it by setting up the method and path of your choice. -## Step 4. API endpoint configuration +You can also create a **new endpoint** by selecting "Http route" in the route menu add button. In this tutorial, we will create a new `GET` endpoint with the path `/users`, which will return a list of randomly generated users: -You can further customize your endpoint by adding a custom header and the following sample body (which makes use of Mockoon's [templating system](docs:templating/overview)): +![Recording of adding a new API route{1468x886}](/images/tutorials/getting-started/create-basic-api-endpoint.gif) + +## Step 4. Body and headers configuration + +We will customize the endpoint by adding a **response body** that will return a JSON of randomly generated users. You can copy and paste the following JSON in the response body field. This template uses our [templating system](docs:templating/overview) to generate random data for each user: ```json // Sample body [ - {{# repeat 5}} - { - "title": "Tutorial {{@index}}", - "tags": "{{someOf (array 'Getting started' 'https' 'proxy mode' 'headers' 'templating') 1 3}}" - } - {{/ repeat}} + {{#repeat 10}} + { + "id": "{{faker 'string.uuid'}}", + "name": "{{faker 'person.firstName'}} {{faker 'person.lastName'}}", + "email": "{{faker 'internet.email'}}", + "phone": "{{faker 'phone.number'}}", + "address": "{{faker 'location.streetAddress'}}, {{faker 'location.city'}}, {{faker 'location.stateAbbr'}} {{faker 'location.zipCode'}}", + "birthdate": "{{faker 'date.past'}}", + "isActive": {{faker 'datatype.boolean'}} + } + {{/repeat}} ] ``` -![Recording of updating an API route{1171x754}](/images/tutorials/getting-started/update-api-route.gif) +We will also add a **Content-Type** header to the response. This header is necessary for the client to understand the response format. In this case, we will set it to `application/json`: + +![Recording of updating an API route{1468x886}](/images/tutorials/getting-started/add-body-template-header.gif) + +> 💡 You can create a more complex configurations by [adding multiple responses triggered by rules](docs:route-responses/dynamic-rules). + +## Step 5. Add a delay to the response + +The last step is to add a **delay to the response** to simulate a real-world scenario where the server takes some time to process the request. This is useful for testing the client's behavior when the server is slow to respond. -You can create a more complex configuration by serving files or [adding multiple responses triggered by rules](docs:route-responses/dynamic-rules). +You can add a delay to the response by setting the **delay** field in the response configuration. In this case, we will set it to 2000 milliseconds (2 seconds): -## Step 5. Run and call your mock API +![Recording of adding a delay to the response{1468x886}](/images/tutorials/getting-started/add-response-delay.gif) -The last step is to run your mock API. For this, click on the green "play" arrow in the header: +## Step 6. Run and call your mock API -![Recording of running a mock API{1171x754}](/images/tutorials/getting-started/run-mock-api.gif) +Finally, you can **run your mock API** by clicking on the green "play" arrow in the header. This will **start the server** and make it available on `http://localhost:3000`. -Your mock server is now available on `http://localhost:3000` (but also on `http://127.0.0.1` and all your local network adapters). +![Recording of starting the mock API{1468x886}](/images/tutorials/getting-started/start-mock-api.gif) -You can do a test call to the following URL `http://localhost:3000/tutorials` using your favorite tool (here using Insomnia) and see the returned response: +You can do a **test cal**l to the following URL `http://localhost:3000/users` using a tool like curl, Postman, or your browser. You should see the list of randomly generated users in the response: -![Screenshot of the result call{1052x458}](/images/tutorials/getting-started/result-call.png) +![Screenshot of the result call{1176x612}](/images/tutorials/getting-started/calling-users-list.png) -## Step 6. Learn more +## Step 7. Learn more -Now that you know how to create a basic mock API, you can head over to the [official documentation](docs:about) to explore the other functionalities like [requests logging](docs:logging-and-recording/requests-logging), [partial API mocking with proxy mode](docs:server-configuration/proxy-mode), or the [templating system](docs:templating/overview). +Now that you know how to create a basic mock API, you can head over to the [official documentation](docs:about) to explore the other functionalities available like [requests logging](docs:logging-and-recording/requests-logging), [partial API mocking with proxy mode](docs:server-configuration/proxy-mode), or the [templating system](docs:templating/overview). diff --git a/content/tutorials/use-environment-variables.md b/content/tutorials/use-environment-variables.md index 22a1517b..25e58acd 100644 --- a/content/tutorials/use-environment-variables.md +++ b/content/tutorials/use-environment-variables.md @@ -34,7 +34,7 @@ To access an environment variable in your templates, use the `getEnvVar` helper. You can **change the prefix** or **remove it** entirely in the desktop application settings: -![desktop application settings showing the prefix input](/images/tutorials/use-environment-variables/settings-environment-variables-prefix.png) +![desktop application settings showing the prefix input{860x812}](/images/tutorials/use-environment-variables/settings-environment-variables-prefix.png) You can also modify the prefix when running your mock with the CLI by using the `--env-vars-prefix` flag: @@ -72,7 +72,7 @@ export MOCKOON_API_TOKEN=abcd1234 In your mock server, we will enable the proxy mode, point to the correct API endpoint (here, the endpoint is a fictive one), and use the `getEnvVar` helper to access the token and add it to an `Authorization` header: -![view of Mockoon proxy settings showing an url and an authorization header](/images/tutorials/use-environment-variables/access-environment-variable-authorization-header.png) +![view of Mockoon proxy settings showing an url and an authorization header{977x376}](/images/tutorials/use-environment-variables/access-environment-variable-authorization-header.png) You can see that we are using the `getEnvVar` helper to access the `MOCKOON_API_TOKEN` environment variable and add it to the `Authorization` header: @@ -84,8 +84,8 @@ Now, when you send a request to a non-existing route, for example, `GET http://l To simulate this, we will point the proxy to another Mockoon instance running on `http://localhost:3001` instead of `https://api.service.com`: -![view of Mockoon proxy settings showing an url and an authorization header](/images/tutorials/use-environment-variables/proxy-mode-local-mock.png) +![view of Mockoon proxy settings showing an url and an authorization header{982x358}](/images/tutorials/use-environment-variables/proxy-mode-local-mock.png) After making a call to our original mock server running on `http://localhost:3002`, we can inspect the forwarded request in the other instance and verify that the `Authorization` header is correctly set: -![view of the forwarded request showing the authorization header](/images/tutorials/use-environment-variables/inspect-forwarded-call-authorization-header.png) +![view of the forwarded request showing the authorization header{1097x473}](/images/tutorials/use-environment-variables/inspect-forwarded-call-authorization-header.png) diff --git a/public/images/tutorials/getting-started/add-body-template-header.gif b/public/images/tutorials/getting-started/add-body-template-header.gif new file mode 100644 index 00000000..c2b8e2f7 Binary files /dev/null and b/public/images/tutorials/getting-started/add-body-template-header.gif differ diff --git a/public/images/tutorials/getting-started/add-response-delay.gif b/public/images/tutorials/getting-started/add-response-delay.gif new file mode 100644 index 00000000..f325d76d Binary files /dev/null and b/public/images/tutorials/getting-started/add-response-delay.gif differ diff --git a/public/images/tutorials/getting-started/app-download-screenshot.png b/public/images/tutorials/getting-started/app-download-screenshot.png deleted file mode 100644 index 6589ff70..00000000 Binary files a/public/images/tutorials/getting-started/app-download-screenshot.png and /dev/null differ diff --git a/public/images/tutorials/getting-started/calling-users-list.png b/public/images/tutorials/getting-started/calling-users-list.png new file mode 100644 index 00000000..80bb5fcc Binary files /dev/null and b/public/images/tutorials/getting-started/calling-users-list.png differ diff --git a/public/images/tutorials/getting-started/create-api-route.gif b/public/images/tutorials/getting-started/create-api-route.gif deleted file mode 100644 index 0d3e681f..00000000 Binary files a/public/images/tutorials/getting-started/create-api-route.gif and /dev/null differ diff --git a/public/images/tutorials/getting-started/create-basic-api-endpoint.gif b/public/images/tutorials/getting-started/create-basic-api-endpoint.gif new file mode 100644 index 00000000..bce85177 Binary files /dev/null and b/public/images/tutorials/getting-started/create-basic-api-endpoint.gif differ diff --git a/public/images/tutorials/getting-started/create-first-mock-api.gif b/public/images/tutorials/getting-started/create-first-mock-api.gif new file mode 100644 index 00000000..2bf6b8b0 Binary files /dev/null and b/public/images/tutorials/getting-started/create-first-mock-api.gif differ diff --git a/public/images/tutorials/getting-started/create-mock-api.gif b/public/images/tutorials/getting-started/create-mock-api.gif deleted file mode 100644 index 9bfbb543..00000000 Binary files a/public/images/tutorials/getting-started/create-mock-api.gif and /dev/null differ diff --git a/public/images/tutorials/getting-started/desktop-application-download-screenshot.png b/public/images/tutorials/getting-started/desktop-application-download-screenshot.png new file mode 100644 index 00000000..09de6335 Binary files /dev/null and b/public/images/tutorials/getting-started/desktop-application-download-screenshot.png differ diff --git a/public/images/tutorials/getting-started/rename-environment.png b/public/images/tutorials/getting-started/rename-environment.png deleted file mode 100644 index 03d0c2f3..00000000 Binary files a/public/images/tutorials/getting-started/rename-environment.png and /dev/null differ diff --git a/public/images/tutorials/getting-started/result-call.png b/public/images/tutorials/getting-started/result-call.png deleted file mode 100644 index e0fa6c17..00000000 Binary files a/public/images/tutorials/getting-started/result-call.png and /dev/null differ diff --git a/public/images/tutorials/getting-started/run-mock-api.gif b/public/images/tutorials/getting-started/run-mock-api.gif deleted file mode 100644 index 3136676a..00000000 Binary files a/public/images/tutorials/getting-started/run-mock-api.gif and /dev/null differ diff --git a/public/images/tutorials/getting-started/start-mock-api.gif b/public/images/tutorials/getting-started/start-mock-api.gif new file mode 100644 index 00000000..338ecbe2 Binary files /dev/null and b/public/images/tutorials/getting-started/start-mock-api.gif differ diff --git a/public/images/tutorials/getting-started/update-api-route.gif b/public/images/tutorials/getting-started/update-api-route.gif deleted file mode 100644 index a0a56847..00000000 Binary files a/public/images/tutorials/getting-started/update-api-route.gif and /dev/null differ diff --git a/public/images/tutorials/tutorial-getting-started.png b/public/images/tutorials/tutorial-getting-started.png index d71575d4..8ff7c962 100644 Binary files a/public/images/tutorials/tutorial-getting-started.png and b/public/images/tutorials/tutorial-getting-started.png differ