# Getting Started

Brief introduction about Mocklets and onboarding process

Welcome to Mocklets.&#x20;

While working on front-end apps(mobile/web), we all have faced issues like delayed back-end deployment and difficulty in reproducing production issues involving connectivity or some other edge cases.&#x20;

Mocklets helps you to navigate through these issues with ease. Mocklets lets you create mock APIs with endpoints similar to the APIs you need from your back-end. This helps front-end developers to start their work alongside the back-end development which saves a lot of development time, also it helps in creating edge case scenarios for better application testing.

*Let's get you your first mock API.*


# Working with Collections

This page will familiarize you with the usage of Mocklets Collections.

Mocklets arranges your mock APIs into different collections. A Collection is a group of mock APIs, which consists of a unique base URL and other settings and can be shared with other users as well.

![Mocklets Collection](/files/-Ldogcka88uvXfdQq29h)

You can add mock APIs or directly import Open API Specification (formerly known as Swagger Specifications) in a collection.

Collection also lets you to setup a proxy environment, where you can set the proxy base url to which all your calls will be forwarded. *Read **Use API as Proxy** for more detail&#x73;**.***

Now lets see how we can create a Collections and invite our team to use it.

{% content-ref url="/pages/-Ldtj7ZI7Kcg2V8Qjb6l" %}
[Create Collection](/working-with-collections/create-collection)
{% endcontent-ref %}

{% content-ref url="/pages/-LdtjFwcOHivQpypS8Sz" %}
[Invite Members](/working-with-collections/invite-members)
{% endcontent-ref %}

These topics contains detailed insight about how to work with Mocklets Collections.


# Create Collection

To create a collection all you need is a name for your collection. Go to your dashboard, then click Create collection button, you will see the create collection dialog.&#x20;

![Create collection dialog](/files/-LeAf30WgNArtYO4mn3x)

Once the collection is created, you will be redirected to its details page, where you can add your mock apis and configure you collection settings.

### Configure you collection

You can modify the collection name after you have successfully created one. You can also manage proxy settings.

![Collection Settings](/files/-LdrAw3gRHMkKWDlOUaN)

Once your collection is all set, its time to invite your team members. We will see how to add your team to your collection in the next section.


# Invite Members

Once your collection is ready, its time to invite your team and get the work started. To add members, go to the collection details page, then click the **Add Member** button.

![Add member dialog](/files/-LeAihm0E24YKB4eoJ1W)

All you need to add a member is their email id. You can also assign and manage their access levels.

**Read:** Members with Read access have Read-only permissions for mock APIs and collection settings. They cannot create or modify any API and cannot update collection settings.

**Write:** Members with Write access have permission to create, update and delete APIs. Although they cannot update collection settings and invite other members.

**Admin:** Members with Admin access have all the permission as "Write" members. Also, they can update collection settings and invite other team members to the collection.


# Managing Mock Apis

This page provides a step-by-step guide to add and manage mock apis using Mocklets dashboard.

Once you have successfully created a collection, now its time to add mock APIs.(You can also import Open API Specifications to create mock APIs, we will discuss that approach in next chapter).

Mock Apis are the basic building blocks of Mocklets. A mock API is a combination of a URL endpoint, headers, HTTP method, and a predefined response body. You can set the API state (Running/Stopped) from the dashboard.

<div align="center"><img src="/files/-LdoniRLITc22ljaMpdS" alt="Sample api listing"></div>

### **Creating a Mock Api**

There are 2 ways to add mock APIs to your Mocklets Collection, either adding mock APIs manually or through importing Open API Specifications. We will learn how to import Open API Specifications later.

![Api create form](/files/-LdtqIltQSVGI0rwuD5a)

Let's walk through the steps of creating your first mock API.

Firstly, set a label, URL endpoint and HTTP method for your mock API. This concludes the request part of your API.

Now, its time to set the response for your API. Set appropriate HTTP status, headers(Content-Type, Content-Encoding), response delay(*optional*) and a response body. You can choose a data type for response body from Content-Type select.

You are all set, now click on **Create Api** button and your API is ready to be used.

Once the API is created, you can make modifications to it. Some of the features that our mock APIs offer is listed below.

{% content-ref url="/pages/-Ldom5-TjnxvXniN5hXx" %}
[Dynamic Responses](/managing-mock-apis/dynamic-responses)
{% endcontent-ref %}

{% content-ref url="/pages/-LsNg0CyWHyHQJvCM509" %}
[URL Regex Matching](/managing-mock-apis/url-matching-rules)
{% endcontent-ref %}

{% content-ref url="/pages/-Ldolow-w8BiHkNGOGnD" %}
[Use API as Proxy](/managing-mock-apis/use-api-as-proxy)
{% endcontent-ref %}

{% content-ref url="/pages/-Ldolg3H1HUpi2UjKCTP" %}
[Randomised Responses](/managing-mock-apis/randomized-responses)
{% endcontent-ref %}

{% content-ref url="/pages/-Ldolx3QyEyt-0OUL3AL" %}
[Response Delay](/managing-mock-apis/response-delay)
{% endcontent-ref %}

{% content-ref url="/pages/-Ldom-KoqbiPJXQ8TDXm" %}
[Using Query Params](/managing-mock-apis/using-query-params)
{% endcontent-ref %}

{% content-ref url="/pages/-LroqTzdV\_axVPOgI7Ij" %}
[API Comments](/managing-mock-apis/api-comments)
{% endcontent-ref %}

These steps contain detailed feature descriptions and their functionality.


# Dynamic Responses

Using Dynamic Responses feature, Mocklets allows you to set up multiple responses for your APIs and select an active one on-the-go to test your web/app across various scenarios, which cannot be simulated with your real server environment.

![](/files/-LdvXLIvS4j-SxZyT9ga)

Each response can have its own set of headers(Content-Type, Content-Encoding), response delay and response body.

This feature allows development as well as QA teams to test their applications, across various scenarios starting from the development phase, resulting in a much more robust and stable product.

If you want your API to return any specific response, which is not currently active, you can do that using query params also. Please refer this link for more.


# URL Regex Matching

Mocklets work on matching your API request URL, but in some cases exact matching on the request URL alone is not specific enough. For instance, you may want to simulate an API **`/api/user/<user_id>/profile`**, where some portion of the URL string is variable. We cannot expect one to create multiple APIs with all the possible matching URL. \
This is can be achieved by adding **RegEx sequence** in your API request URL.

![](/files/-M-ueTJkC1V22ACbKSeR)

To enable **RegEx** matching for your API, just replace the variable section of the URL with **`{...}`**. Mocklets system will auto detect the **RegEx** placeholder and validate it against the incoming request URL.

For example in the above screenshot, the mock API provided with path as **`https://api.mocklets.com/mock67795/user/{...}/profile`** is a valid candidate for requests like **`https://api.mocklets.com/mock67795/user/123456/profile`**&#x6F;&#x72;**`https://api.mocklets.com/mock67795/user/c81d4e2e-bcf2-11e6-869b-7df9253/profile`**.

If you want to add any regex element in the API path, use **`{...}`** in its place and later while making request to that API, replace **`{...}`** with actual text.&#x20;

In order to be valid regex match, the actual text should only be comprised of the following.\
**`Alphabets    a-z A-Z`**\
**`Numbers      0-9`**\
**`Symbols      _ - = + . @`**

> You can also verify your text for regex validation here [***https://mocklets.com/regex***](https://mocklets.com/regex).


# Use API as Proxy

When working with an existing API it can be useful to pass some requests through to it for testing, while serving mock responses for others.

For instance, if an API is not yet fully implemented then testing progress can still be made for the calling application by mocking the parts not yet completed.

Additionally, proxying all but a selection of APIs enables testing of edge and failure cases that would be hard to replicate predictably in the target API.

### How to configure proxy settings

![](/files/-LronXuSq-ARQwByE1WM)

You can configure proxy settings for each of your mock API. All you have to do is click the **Configure proxy server** icon and provide the the proxy url you want to forward your mock API request.

![](/files/-LromOXTd_AX9rgtJxj5)

Once you are done with configuring your proxy settings, you can now enable **Use API as Proxy** settings to start proxing your call to the provided url.

![](/files/-LrooYjwRYK-31znduZM)

Once a mock API is configured and enabled to serve a proxy response, all of the normal request matching rules apply, but instead of returning a saved response, the request is forwarded to the target url.

The endpoint of a request’s URL will be replaced by the proxy url i.e. `if` a request made to `https://api.mocklets.com/mock12675/pets` would result in a proxy request to `https://your.server.com/pets`.

Whenever a request is proxied, Mocklets adds 2 headers to the response with the details about the proxied request.

```
x-mocklets-proxy-url: https://your.server.com/pets
x-mocklets-type: proxy
```


# Randomised Responses

The behavior of production APIs in real-world scenarios is all but reliable. Due to various constraints (like network congestion, bad request from client side or even sometimes server failures), your back-end APIs might behave in different ways, producing different responses.

In the **Dynamic Responses** section, we learned that you can add the possible outcome of an API to the Mocklets dashboard. But what if you want your API to return one of the responses randomly instead of the currently active response?

Generating random responses from the API on every request gives a true sense of working with a real-world API.

### How to make an API to return random responses

![](/files/-Lroq57BM-wKMdOaAl5n)

It's very simple to set your API to return random responses on every request. Just enable **Randomised Responses** settings of your API, and your API will starting one the response set in your api on a random basis. If enabled, this setting will override the active response.

{% hint style="info" %}
**Please note** If you have enabled the **Use Api as Proxy**, this feature will be overridden and you will receive the response sent by your proxy server.
{% endhint %}


# Response Delay

Requests over a network to an API can be delayed for many reasons e.g. network congestion or excessive server load. For applications to be resilient they must be designed to handle these inevitable variabilities and tested to ensure optimum end user's experience, even when the back-end APIs are not working properly.

![Setting Response delay to api](/files/-Ldt2zyhLAu4DapsqE8n)

Mocklets provides a very easy way to test applications against these unexpected delays in back-end APIs. Mocklets lets you set response delays to each response, so you can test your application against different HTTP status codes and their respective delays.

The above api will respond with a delay of `10 seconds`.

Whenever Mocklets is instructed to add a delay in response, it adds a header `x-mocklets-delay` to the response.

You can also control the delay duration using query params. Please refer this [link](https://docs.mocklets.com/managing-mock-apis/using-query-params) for more.

{% hint style="info" %}
**Please note** If the API is set to forward the request to the Proxy server, delay settings will be ignored and response will be returned as soon as the proxy server responds.
{% endhint %}


# Using Query Params

When working on a mock API, you will often need to configure your API in a way that will affect the working of the rest of your team. So to handle those scenarios, Mocklets enables you to control some of the configuration using query params while making the API request.

Currently, we allow users to configure response HTTP status and delay parameters by adding query params to their API calls.

### Configure HTTP Status

You can request a specific HTTP status in response by adding `x_response_status` param to your api. So, if you api is `https://api.mocklets.com/mock12675/pets` which has its active response HTTP status set as `200`, but you want it to return a `401` response, you just have to call

```http
https://api.mocklets.com/mock12675/pets?x_response_status=401
```

{% hint style="info" %}
**Please note** You need to add the requested status code to your api, otherwise it will return `404 NOT FOUND`  error.
{% endhint %}

### Configure Response delay

User can add custom delay to the api request using query param without effecting the behavior of other team members using the same api. You need to add `x_response_delay` param to you api. So, if your api is `https://api.mocklets.com/mock12675/pets` and you want to set the delay as `15 seconds`, you have to call

```http
https://api.mocklets.com/mock12675/pets?x_response_delay=15
```

The maximum delay supported in `60 seconds`, any value above it will be ignored and `60 second` delay will be set for that request.

We are adding more configuration that can be managed using query params. Please stay tuned for more.


# API Comments

When working in teams, it is very important to provide a communication channel to record the conversations regarding the API. Mocklets provide the Comments feature to facilitate this communication between the members.

![](/files/-Lrow28Cr6xLxHK5iss8)


# Manage your files

Mocklets now allows you to host your files and assets which you can use in yout mock apis. Let's see how you can upload yout files and assets to Mocklets server.

![Sample Files listing](/files/-LlvYvfGe21Dsbh3MWhV)

Well, now adding file to Mocklets server is super easy, you just have to provide file location and a name for your file.

![](/files/-Llv_gOGlAbVNtBd1V50)

{% hint style="info" %}
Max file size supported is 100KB, if you need higher size limit drop us a line.
{% endhint %}


# Open API Specifications 3.x

This page provided insight about how you can use Open API Specifications to create mock api.

{% hint style="warning" %}
&#x20;This feature is still in Beta phase.
{% endhint %}

Open API Specification is the most widely used description language for REST APIs. Mocklets supports the automatic generation of mock APIs from imported Open API Specifications. You just have to upload your specs on Mocklets dashboard.

![](/files/-LdtaPwoXRO4sWhhL775)

Go to the Collection page and click the **Open API Spec** button. Then paste your YAML definition into the text editor, pick your duplicate policy and hit **Upload Specification**.

{% hint style="info" %}
&#x20;Currently, we are only supporting version 3.x of Open API Specification. If you have any older version, please let us know. We will try to provide support for as many versions as possible.
{% endhint %}

### Duplicate Policy

If you’re working with an Open API Specification which is changing on a regular basis, you’ll probably want to re-import it repeatedly.

This means you have to decide what to do when a stub is newly generated for a URL/content type combination for which a stub already exists from a previous import. Most of the time, for the sake of keeping the mock API correct you’ll want to overwrite the previous stub, so this is the default behavior set on the dashboard. However, you also have the option of skipping the already created mock APIs and keep the data for those APIs the same as a previous import.


# Integration with external editors

*`Integration with external editors documentation under progress.`*


# Response Headers

This page will help you make sense and use of the response headers attached by Mocklets platform.

When an API request is sent to the Mocklets server, it responds with the data set by the user for that API. But apart from the user data, Mocklets also returns other configuration data as response headers which help in debugging the request. Here are the headers which Mocklets returns.

### x-mocklets-src

This header lets what is the source of the response data. It can have 2 values `mock` or `proxy`. If the value is `mock` it means the data is fetched from the mock response provided the user, and if the value is `proxy`, it signifies that the response served to the user is from proxy server.

### x-mocklets-proxy-url

�This header is returned when the api request has been forwarded to a proxy server. It contains the url of the proxy server to which the request has been forwarded to.

### x-mocklets-delay

This header signifies the delay added to the api request (in seconds).

�


# Monitor Request Logs

This page is about api monitoring and analysis.

Mocklets gives you a detailed insight into the usage of your APIs. Mocklets list all the API requests for the last 1 week in chronological order. You can analyze the request and response parameters.

![Api Request details](/files/-Ldz2Dpdu3uYncfMlDGY)

![Api Response details](/files/-Ldz2ONPg1Hqe5hycQTT)

We are continuously adding a new matrix to our API monitoring. Please reach out to us if you need any specific matrix to analyze.


# Secure your mock APIs

Secure your APIs against unauthorized use.

Now that Mocklets APIs are being used in production environment to manage Application Configuration and experiment with new features, there is a need to secure the APIs against unauthorized use.

Collections have a Private key associated to them. You will find it in Auth Credentials in Collection Settings dialog.

![](/files/-LszMlCsL7faK8mxked2)

To set an API as secured, just select the option **Mark API as Secure** in API settings.&#x20;

![](/files/-LszN7EGBOyKqK3R1-W8)

That's it, your API is now secure! \
Now all the unauthorized requests to the above API will start failing.

### Making Authorized requests

Once your API is set as secured, you cannot connect to it through unauthorized requests. In order to make an authorized request, you need to provide Auth headers with your requests.

```yaml
X-Mocklets-PublicKey : PUBLIC_KEY
X-Mocklets-Checksum : b2b449452e99c7804585021971fb7a84
```

**X-Mocklets-PublicKey**\
Public key is a string value used by client system to create the checksum. Public key is created by the client.

**X-Mocklets-Checksum**\
To generate checksum, you have to create **MD5 hash** string for **Public key (**&#x70;rovided in X-Mocklets-PublicKey heade&#x72;**)** and **Private key** (from Mocklets collection settings) pair.

```
checksum = MD5_HASH(PUBLIC_KEY : PRIVATE_KEY)
```

Please refer the following code snippets to generate MD5 Hash.

{% tabs %}
{% tab title="Java" %}

```java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
.
.
String plainText = PUBLIC_KEY + ":" + PRIVATE_KEY;

MessageDigest md = MessageDigest.getInstance("MD5");
byte[] hashInBytes = md.digest(password.getBytes(StandardCharsets.UTF_8));

StringBuilder builder = new StringBuilder();
for (byte bt : hashInBytes) {
    builder.append(String.format("%02x", bt));
}

String checksum = builder.toString();
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
import java.security.MessageDigest
.
.
val plainText = PUBLIC_KEY + ":" + PRIVATE_KEY
val bytes = MessageDigest.getInstance("MD5").digest(plainText.toByteArray())

val builder = StringBuilder()
for (bt in bytes) {
    builder.append(String.format("%02x", b))
}

val checksum = builder.toString()
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const md5 = require('md5');
.
.
const checksum = md5(PUBLIC_KEY + ':' + PRIVATE_KEY);
```

{% endtab %}

{% tab title="Python" %}

```python
import hashlib
.
.
md5 = hashlib.md5()
md5.update(PUBLIC_KEY + ":" + PRIVATE_KEY)
checksum = m.hexdigest()
```

{% endtab %}
{% endtabs %}

You can also use online MD5 hash generator tools to create checksum value. One such tools is [**https://www.md5online.org**](https://www.md5online.org).&#x20;

![online MD5 generator](/files/-Lt0sacy-9NPI1WHcoeU)


