Creating Mock API with API Creator

Quick API Creation

An API can be instantly created through API Documentation or containing default CRUD operations, and instantly opened to users' access as an API Proxy.

Conditional Responses

Apinizer enables obtaining different responses according to conditions based on request header, body, or parameter values thanks to conditions added to the response.

API Documentation

The OpenAPI specification of a Mock API can be viewed, copied, and downloaded on the fly in YAML and JSON formats.

Mock API List

Select Development → API Creator → Mock API in the main menu. The page shows all Mock APIs in one card.

Type a name in the search box above the table to filter the list. Click the clear button next to the search box to reset the search.

The table has these columns:

Column	Description
Name	The name of the Mock API. Its description appears under the name. Click the name to open the editor. Click the column header to sort the list by name.
Endpoints	The number of endpoints in the Mock API.
API Proxies	The number of API Proxies that route to this Mock API.
Version	The version of the Mock API. The OpenAPI specification shows this value as the API version.
Last modified	The time of the last change and the user who made it. A recent change shows Just now, Today, 14:05, or Yesterday, 09:30. If you made the change, the user is you.

Note

A Mock API that you created before the version field existed shows the version 1.0.

The ... menu at the end of each row has these actions:

Action	Description
Open editor	Opens the Mock API editor.
Duplicate	Opens a dialog. Enter a new name to create a copy of the Mock API.
Export	Opens the Export/Import wizard for this Mock API.
Download OpenAPI spec	Downloads the generated OpenAPI specification as a YAML file.
Delete	Deletes the Mock API. See Mock API Deletion.

The breadcrumb bar above the list has two buttons:

Button	Description
Import	Opens the Export/Import wizard with the API Creator type. Use it to import a file that you created with Export. For details, see Export/Import.
Create	Opens the page where you create a new Mock API. See Creating New Mock API.

Note

Import does not import an OpenAPI or Swagger specification. To create a Mock API from a specification, click Create and select Import a specification.

Creating New Mock API

Click Create in the breadcrumb bar of the Mock API list. The new Mock API wizard opens in a card. The wizard has three steps: Source, Details, and Review.

• Click Continue to go to the next step.
• Click Back to return to the previous step. In the first step, Cancel returns to the Mock API list.
• If Continue is disabled, the footer shows the reason, for example The name is required.

Select the Source

Under How do you want to start?, select Start blank or Import a specification.

• Start blank creates an empty Mock API. You define the operations, responses, and examples in the editor.
• Import a specification creates the Mock API from an OpenAPI 3.x or Swagger 2.0 document. See Importing a Specification.

Enter the Details

Enter the Name of the Mock API. Enter the Description and the Version if necessary. For Start blank, you can also turn on the CRUD scaffold.

Review and Create

Check the summary. Click Create mock API. Apinizer creates the Mock API and opens its editor.

Importing a Specification

When you select Import a specification, more fields appear under the source cards.

Select the Format

Under Specification format, select OpenAPI 3.x or Swagger 2.0.

Select the Source of the Document

Under Source, select From URL, Upload file, or Paste.

• From URL: Enter the address of the document. The Apinizer management server must reach this address. Click Use a sample URL to fill in a sample address.
• Upload file: Click Choose file and select a .json, .yaml, or .yml file.
• Paste: Paste the content of the document into the text area.

Parse the Document

Click Parse. Apinizer reads the document and resolves its $ref components. If Apinizer cannot read the document, an error message appears. In this case, check the format, the source, and the content.

Select the Operations

A card shows the title of the specification, the number of operations and examples, the format, and the version. The list under Operations to import shows the method, the path, the summary, the status codes, and the number of examples of each operation. All operations are selected. Clear the operations that you do not want to import. Select at least one operation.

The wizard fills in the Name, the Description, and the Version from the specification. You can change them in the Details step.

Info

The import keeps the examples of the specification. If a JSON response has no example, Apinizer creates an example from its schema. The import also keeps the summary, the operationId, the tag, the parameters, and the request body of each operation.

CRUD Scaffold

For Start blank, the Details step shows the CRUD scaffold option. Turn on Generate list, create, read, update and delete operations to add five endpoints for one resource. Enter the Resource name, for example customers. The default resource name is items. Apinizer uses only the letters, the digits, "-", and "_" of the name, in lower case.

The list under the field shows the endpoints that Apinizer creates. For the resource customers, the endpoints are:

Method	Path	Response
GET	/customers	200 with a list of sample records
POST	/customers	201 with a sample record
GET	/customers/{id}	200 with a sample record
PUT	/customers/{id}	200 with a sample record
DELETE	/customers/{id}	204 without a body

Each endpoint has a summary, an operationId, and a tag. The endpoints with {id} have the path parameter id. The POST and PUT endpoints have a JSON request body with a schema.

Wizard Fields

Step	Field	Description
Source	Start blank / Import a specification	Selects how to start the Mock API.
Source	Specification format	OpenAPI 3.x or Swagger 2.0.
Source	Source	From URL, Upload file, or Paste.
Source	Operations to import	The operations of the specification to add to the Mock API.
Details	Name	Required. The name of the Mock API. The API catalog shows this name. The OpenAPI specification uses it as the API title. Apinizer checks that the name is unique.
Details	Description	A short description of the Mock API.
Details	Version	The version of the Mock API. The default value is 1.0.0. The OpenAPI specification uses it as the API version.
Details	CRUD scaffold	Only for Start blank. Creates list, create, read, update, and delete endpoints for one resource.
Details	Resource name	The resource of the CRUD endpoints.

The Review step shows the name, the description, the source, and the version. It also lists the operations that Apinizer creates. Next step tells you to create an API Proxy to expose and test the Mock API.

Mock API Editor

The editor opens after you click Create mock API in the wizard. You can also open it from the list: click the name of the Mock API, or select Open editor in the ... menu. The editor has a left column, a center area, and breadcrumb buttons.

Info

Each panel and dialog that changes data has its own Save button. Save stores your changes at once.

Left Column

• The name and the version of the Mock API are at the top, for example Customer Accounts v1.0.0. The description and a summary line are below them. The summary line shows the number of endpoints, examples, and API proxies.
• The pencil button opens the Edit name, description and version dialog. Change the values and click Save. Apinizer saves the change at once. The OpenAPI specification uses the version as the API version.
• API Endpoints lists the endpoints. The + button adds a new endpoint. The search box filters the list.
• The list groups endpoints by the first segment of the path. For example, /customers and /customers/{id} are both under CUSTOMERS.
• Each endpoint card shows the method, the path, the summary or the description, and the status codes of the responses. It also shows the number of examples and how many of them are conditional, for example 3 examples · 1 conditional.
• Hold the pointer on a card to see the full path and the description.
• Click a card to select the endpoint. The selected card is highlighted.

Center Area

The center area has two cards: the endpoint card and the Responses card.

The top of the endpoint card shows the method, the path, and the summary of the selected endpoint. If the endpoint has no summary, the description appears. The actions of the endpoint are on the right, in this order:

Action	Description
Try it	Opens the Try it panel for this endpoint. See Try it. If the Mock API has no API Proxy, the button is disabled. Hold the pointer on the button to see the reason.
Configure	Opens the Configure panel of the endpoint. See Endpoint Creation.
Duplicate	Creates a copy of the endpoint.
Delete	Deletes the endpoint after you confirm.

Only users who can manage API Creator see Configure, Duplicate, and Delete.

The endpoint card also shows the definition of the endpoint. The definition is read-only. To change it, click Configure.

Row	Description
operationId	The operation ID in the OpenAPI specification.
Tag	The tag of the operation in the OpenAPI specification.
Request body	The media type of the request body, and required or optional. None means that the endpoint has no request body.
Description	The description of the endpoint. This row appears only when the endpoint has a description.
Parameters	One badge for each parameter, for example id · path · integer · required. No parameters. means that the endpoint has no parameters.
Request body fields	One badge for each property of the request body schema, for example name · string · required. This row appears only when the endpoint has a request body.

A gray operationId or Tag value is a generated value. The endpoint has no value of its own, so the specification uses the generated value. Hold the pointer on the value to see this note.

The Responses card shows the responses of the endpoint. See Adding or Editing Response.

Breadcrumb Buttons

The breadcrumb bar has these buttons, from left to right:

Button	Description
Back	Returns to the Mock API list.
Show Specs (eye icon)	Opens the OpenAPI specification of the Mock API in a dialog. Switch between the Open API Yaml tab and the Open API JSON tab. Use Copy to Clipboard or Download to copy or download the specification.
Manage API Proxies	Shows the API Proxies created from this Mock API and their deployment status. See Deploy/Redeploy.
Create API Proxy	Opens the Create API Proxy dialog. See Creating API Proxy from Mock API.
More actions (⋯)	Opens a menu. Transfer > Export opens the Export/Import wizard for this Mock API. History > Audit and Rollback opens the audit and rollback records of the Mock API in a side panel; for details, see Asset Lifecycle. Delete followed by the Mock API name, in red at the end of the menu, deletes the Mock API.

Endpoint Creation

Info

The CRUD scaffold of the wizard creates five endpoints for one resource. You can change these endpoints in the editor.

Add Endpoint

Click the + button next to API Endpoints. If the Mock API has no endpoint, you can also click Add in the center area. The Configure panel opens from the right. Its title is New endpoint.

Fill Endpoint Information

Select the HTTP method and enter the path. Fill in the other fields if necessary. Click Save. Apinizer adds the endpoint to the Mock API with one 200 OK response.

To change an endpoint, select it and click Configure in the endpoint card. The title of the panel shows the method and the path of the endpoint.

The Configure panel has three parts: Definition, Parameters, and Request body.

Definition

Field	Description
HTTP Method	Required. Select GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS.
Path	Required. The relative address of the endpoint. Write path parameters in braces, for example /customers/{id}. Apinizer adds each path parameter to the parameter list. A Mock API cannot have two endpoints with the same method and path.
Summary	A short summary of the operation. If it is empty, the specification uses the description.
operationId	The operation ID in the OpenAPI specification. If it is empty, the specification uses the generated value that the field shows in gray, for example get_customers. Two endpoints cannot have the same operationId.
Tag	The tag of the operation in the OpenAPI specification. If it is empty, the specification uses the name of the Mock API.
Description	A description of the endpoint.

Parameters

The Parameters part appears when the endpoint has parameters. To add the first parameter, click + Parameters next to Add field: at the bottom of the panel. Each parameter row has these fields:

Field	Description
Name	The name of the parameter. Two parameters cannot have the same name and location.
Location	path, query, header, or cookie.
Type	string, integer, number, boolean, or array.
Required	Marks the parameter as required. A path parameter is always required.
Example	A sample value. Try it fills in the parameter with this value.
Description	A description of the parameter.

Click + Parameter to add a row. Click the delete icon of a row to remove it. When you change the path, Apinizer adds and removes the path parameters.

Request body

The Request body part appears when the endpoint has a request body. To add it, click + Request body next to Add field: at the bottom of the panel.

Field	Description
Media type	The media type of the request body, for example application/json. Select a value from the list or type a value.
Required	Marks the request body as required.
Schema (JSON Schema)	The JSON Schema of the request body. The label next to the title shows Valid JSON or Invalid JSON. The schema must be a JSON object. The OpenAPI specification shows this schema. Try it creates a sample body from it.

Click Remove to remove the request body.

The footer of the panel has these buttons:

• Delete endpoint deletes the endpoint after you confirm. This button is not shown for a new endpoint.
• Cancel closes the panel and discards your changes. If the endpoint is new, Apinizer does not create it.
• Save stores the endpoint at once.

The endpoint card has two more actions:

• Duplicate opens the Configure panel as a new endpoint. The new endpoint has a copy of the selected endpoint and its responses. The path gets the suffix -copy. The operationId of the copy is empty. Change the path if necessary and click Save.
• Delete deletes the selected endpoint after you confirm.

Adding or Editing Response

The Responses card shows the responses of the selected endpoint. Each status code is a tab, for example 200 OK and 401 Unauthorized. The + Add button after the tabs adds a response.

Info

Response definitions are grouped by status code. Each response can have several examples. Examples differ by media type and by conditions.

Select a tab to see its response. The card shows the description of the response, the number of headers, and the Edit response button. The table of examples is below them.

• To edit a response, select its tab and click Edit response.
• To add a response, click + Add after the status tabs.

Both actions open the response panel from the right. The title of the panel shows the status code. The line above the title shows the endpoint.

The response panel has three parts: Status, Content, and Headers.

Field	Description
Status Code	In the Status part. The HTTP status code of the response. Select it from the list. Type in the list to filter it. An endpoint can have only one response for each status code.
Description	In the Status part. Required. A short description of the response.
Content	The media types of the response and their examples. The badge next to the title shows the number of media types.
Headers	The HTTP headers of the response. The badge next to the title shows the number of headers.

The Content part works as follows:

• Select or type a media type and click Add. Each media type gets its own button.
• Select a media type button. A table shows the examples of this media type: the name, the badge, the conditions, and the body. The body appears in a read-only code editor.
• Click the pencil icon of a row to edit the example. Click the delete icon of a row to remove the example.
• Click + Example to add an example to the selected media type.
• Click Remove to remove the selected media type with all its examples.

The Headers part appears when the response has headers. To add the first header, click + Headers next to Add field: at the bottom of the panel. Then:

• Click + Header to add a row.
• Enter the name and the value of the header. The fields suggest common header names and values.
• Click the delete icon of a row to remove the row.

The footer of the response panel has these buttons:

• Delete response deletes the response after you confirm. This button is not shown for a new response.
• Cancel closes the panel. Apinizer discards the changes that you made since you opened the panel.
• Save stores the response at once. Apinizer records the change in the Audit and Rollback records (More actions > History).

Adding or Editing Response Examples

An example is a response body that Apinizer returns. A response can have several examples. Each example belongs to one media type. Add conditions to an example to send different responses to the client under different conditions.

The table under the selected status tab lists the examples of the response. It has these columns:

Column	Description
Media type	The media type of the examples, in bold. One cell covers all examples of the same media type. Click the media type to open the response panel with this media type selected.
Example	The name of the example, for example Example 1, and its badge.
Conditions	The conditions of the example, or No conditions.
Body	The response body in a read-only code editor.

A badge shows how Apinizer uses each example:

Badge	Description
Default	The example has no conditions. Apinizer returns it when no conditional example matches.
N rule	The example has conditions. N is the number of rules. Apinizer returns the example when the request meets the conditions.
Unused	The example has no conditions, and another example without conditions exists in the same media type. Apinizer never returns it.

Info

If no example matches the request, Apinizer returns the status code 204.

A click on a table row has no effect. To edit examples, click the media type or Edit response. Both open the response panel.

Each media type group ends with + Example. It opens the example dialog directly. Save in the dialog stores the example at once. If the response has no examples, the table shows No examples yet. and + Example. This button adds an example with the media type application/json.

The example dialog shows the location of the example, for example GET /customers › 200 OK › application/json, and the title Example · Example N. Fields used for Example Response add/edit configuration are shown in the table below.

Field	Description
Name	Optional. The name of the example. If it is empty, the tables show Example N.
Conditions	The condition builder. Choose AND or OR, and click New Rule or New Rule Set to add rules. A summary sentence under the builder shows when Apinizer returns the example. If the example has no rules, the sentence says that Apinizer returns it when no conditional example matches.
Response Body	The body that Apinizer returns to the client. The code editor shows Valid JSON or Invalid JSON.
Variables	A menu with Global Variable and Context Variable. Each item opens a helper dialog. Select a variable in the dialog to copy it. Paste it into the body.
Format	Formats the body as JSON. If the body is not valid JSON, Apinizer shows an error message.

An example belongs to the media type that you opened the dialog from. An example without conditions is the default example. An example with conditions is a conditional example.

The footer of the dialog has these buttons:

• Delete removes the example. It appears when you open an existing example from the response panel.
• Cancel closes the dialog and discards your changes.
• Save stores the example.

Info

If you open the example dialog from the response panel, Save returns you to the panel. Apinizer stores the change when you save the panel.

Try it

Try it sends a real request through an API Proxy to the selected endpoint. The panel shows the response of the Mock API.

Note

Try it uses the same request service as the Test Console. You need the Execute permission for Test Console.

Info

Try it needs an API Proxy that routes to the Mock API. If the Mock API has no API Proxy, the Try it button is disabled. Create an API Proxy first. See Creating API Proxy from Mock API.

Open Try it

Select an endpoint in the left column. Click Try it in the endpoint card. The Try it panel opens from the right.

Select API Proxy and Environment

The API Proxy list and the Environment list are on one line. The panel selects the first API Proxy and its first environment. To change them, select another API Proxy. Then select the Environment. Each API Proxy item shows the name and the relative path. The Environment list shows only the environments where the API Proxy is deployed.

Prepare the Request

The Request part shows the method and the full request URL. The URL contains the access URL of the environment, the relative path of the API Proxy, and the path of the endpoint. Change the request in the tabs of the request card. See the table below.

Send the Request

Click Send at the end of the URL line. The Response part appears below the request.

The request card has these tabs:

Tab	Description
Parameters	The path parameters and the query parameters. Each path parameter has the path badge and a value field, for example id in /customers/{id}. Click + Add to add a query parameter. Click the remove icon of a row to delete it. The badge on the tab shows the number of parameters.
Headers	The request headers. Click + Header to add a header. Click + Prefer to add a header named Prefer. The badge on the tab shows the number of headers.
Body	The request body in a code editor. This tab appears for methods that carry a body, for example POST, PUT, and PATCH. For these methods, the panel opens on this tab.

The panel fills in the request from the endpoint definition:

• Each parameter gets its example value.
• The Headers tab starts with the header Accept: application/json. The header parameters and the cookie parameters of the endpoint follow it.
• For methods that carry a body, the panel adds the Content-Type header. Its value is the media type of the request body, or application/json.
• The Body tab gets a sample body from the JSON Schema of the request body.

Two buttons are on the right of the request tabs:

• Copy cURL copies the request as a cURL command.
• Reset restores the request to its starting values.

The Response card has these parts:

Part	Description
Status	The status code and the status text, for example 200 OK. The color of the badge shows the status class.
Time	The response time in milliseconds.
Size	The size of the response.
Body tab	The response body in a read-only code editor. Apinizer indents a JSON body. The values do not change.
Headers tab	The response headers in a table with the columns Name and Value. The badge on the tab shows the number of headers.

An API Proxy that is not deployed shows the Not deployed badge in the list. If you select it, the Environment list is disabled and shows Not deployed. The Request part does not appear. To send requests, deploy the API Proxy. See Deploy/Redeploy.

If the panel finds no API Proxy for the Mock API, it shows No API Proxy for this API yet and a Create API Proxy button.

Creating API Proxy from Mock API

When the Mock API has at least one endpoint, click the Create API Proxy button in the breadcrumb bar. The Create API Proxy dialog opens.

Info

At least one endpoint must exist to create an API Proxy from Mock API. Until then, the Create API Proxy button is disabled.

The dialog suggests a name and a relative path from the name of the Mock API. Change them if needed. The dialog has these fields:

Field	Description
Proxy name	Required. The name of the API Proxy. Apinizer checks that the name is unique.
Relative Paths	The paths that route requests to the API Proxy. Each path must start with "/". If the project uses a relative path prefix, the prefix appears before each path. Click + Add a path to add a path.
Methods	Select one or more methods in the list: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, or QUERY. If you select none, Apinizer routes all methods.
Hosts	Click + Add a host to add a host.
Headers	Click + Add a header to add a header with a name and a value.
Category List	Type a category and press Enter to add it.
Deploy to	One check box for each environment, with the access URL of the environment.
Gateway URL	A preview of the URL that clients use to reach the API Proxy.

Relative Paths, Methods, Hosts, and Headers form the Client Route section. Define at least one path, method, host, or header. For details, see Client Route Settings.

The first environment is checked by default. Clear the check box if you do not want to deploy now.

Click Create and deploy. Apinizer creates the API Proxy and deploys it to the checked environments. If you check no environment, Apinizer only creates the API Proxy. Click Cancel to close the dialog without creating an API Proxy.

After this step, what can be done is exactly the same as the API Proxy document. You can refer to the API Proxy Creation page for details.

Deploy/Redeploy

You can deploy an API Proxy when you create it. Check an environment under Deploy to in the Create API Proxy dialog. You can also manage deployment later with the Manage API Proxies button in the breadcrumb bar.

The panel opened by the Manage API Proxies button is used to view and manage deployment statuses of API Proxies in Mock API.

In the opened panel, Deploy/Undeploy and Redeploy operations for API Proxies created with Mock API are performed in this section. You can refer to the Deployment, Redeployment, Undeployment, Deployment History and Rollback page for details.

To deploy the API Proxy, the following steps are followed.

After the above operation, confirmation is required. Information about the deployment operation is created and the (Deploy) Deploy button is clicked.

Warning

When you add a new endpoint, or you save a change in an endpoint, a response, or an example, redeploy all API Proxies created from this Mock API. Otherwise the changes do not take effect.

After you save a change, the Redeploy required notice appears next to Manage API Proxies, as in the following image.

By saying Redeploy, changes are applied to API Proxies.

After the above operation, confirmation is required. Information about the redeployment operation is created and the (Redeploy) Redeploy button is clicked.

From the Mock API page, go to the API Proxy by clicking the API Proxy's name.

Similarly, to go to the Mock API page from the API Proxy page, go by clicking the Mock API name in the API Proxy as shown below.

Mock API Deletion

To delete a Mock API, click the ... menu at the end of its row in the Mock API list and select Delete. A dialog asks you to confirm. It lists the API Proxies that Apinizer deletes with the Mock API. Enter the name of the Mock API and click Delete.

When a Mock API is deleted, all API Proxies connected to it are first removed (undeploy) and then deleted.