Page tree
Skip to end of metadata
Go to start of metadata

To open the API designer, open the Profound.js IDE and click New > API File to add a new API, or edit an existing file with the extension "api.json."

While you are editing or adding an API File, the following API Designer will be presented:

This API Designer has several sections:

1. Files Tree tab: In this example, you'll see that an API file (a filename that ends with .api.json) was opened.


2. APIs section: This is a list of APIs stored within this file. Here is where you will select, add, update, copy, and remove APIs.


3. This is where you will provide information about the selected API.

  • Within the General Info section:
    • Name: This is used internally and needs to be unique to this file.
    • Summary: This is a short description of what this API does.
    • HTTP Method: The method type used to access this API: 'get' (retrieve information), 'delete' (delete information), 'put' (update information), and 'post' (everything else)
    • HTTP Path: This is the URL path that will activate this API. For example:
    •     /customers      This would represent a RESTful API to get a list of customers
    •     /customer/:id   This would represent a RESTful API to get a single customer for which its ID column equals this path input parameter
    • Category and Sub Category:  These allow you to categorize APIs for easier search and maintenance. These fields are used to create a directory of categorized APIs when you use the Find API File option.
    • Tag: Another way to categorize your APIs.
    • Description:  Describes this API. This field supports CommonMark. This will help the consumers of this API as well as future maintainers of this API.
    • Use CORS: Check this if you want this API to be accessible to other websites, including other internal web servers.
    • Deprecated: Check this if you want to mark this API as deprecated or soon to be removed. The API will appear as deprecated in the Documenting Your APIs.
    • Disabled: Check this if you want to disable this API from being served.
  • In the Output Info section:
    • The Output Info section allows you to describe the output of your API if it generates output. Describing the output helps consumers of the API and improves future maintenance of the API. Output parameters are not validated; their only purpose is to better document what the API returns.
    • Description: Describes what is being returned by this API.  This field supports CommonMark.
    • Output Parameters: (See additional information in the Input Parameters section below regarding drag-and-drop and creating complex objects)
      • Name: Unique name for this parameter (at this level)
      • Data type: The type of value that will be sent from the API.
      • Is Array: Check if the value is an Array. This is used with the Data Type to better describe a parameter, such as an array of integers.
      • Deprecated: Check this if you want to mark this parameter as deprecated or soon to be removed.  The parameter will appear as deprecated in the Documenting Your APIs.
      • Description: Describe the parameter.  This field supports CommonMark.
  • In the Test section:
    • You can test your API, seeing all of the parameters along with your API result
  • In the Stats section
    • You can view usage about this API, such as
      • Number of requests
      • Average response time
      • Average payload size


4. API Logic section: This is where you write your business logic for the selected API.

The API framework will encapsulate your logic within its own function.

  • Write your logic to just be the code within a function
  • Your logic should return a javascript object
  • The framework will run your logic and return this object back to the caller in JavaScript Object Notation (JSON)
  • For advanced usages you can access the node express request and response objects within this code block.
  • If you send your own response the framework will send nothing.

In your code block, you can do whatever is needed, including interacting with:

  • Databases: Using internal APIs such as pjs.data or pjs.query()
  • IBM i programs: Using pjs.call()
  • Node.js packages
  • External web services
  • Other modules/programs


5. Input Parameters section: This is where you will define inputs for the selected API, as well as order and document them.

  • All parameters are validated before running any of the API logic.
  • You can add nested child parameters.  Simply add a body parameter with the type "object", select it, and click the add parameter icon again. This new parameter dialog will not ask where the parameter is coming from because the designer already knows that it will be from that parent body parameter.
  • You can also drag-and-drop the parameters to order them as you like.

For each parameter you define, you can specify:

  • Name: Unique name for this parameter (at this level)
  • From: Where will the value need to come from
    • query is for simple values and used with GET HTTP methods
    • header parameter are not commonly used as parameters, but they are supported
    • body is for more complex values such as all of the parameters for adding a new customer
      • body parameters are not supported with HTTP GET or DELETE methods.
  • Data type: The type of value that will be sent to the API.
    • When "from" is set to "body", a new item becomes available called "object", allowing for complex parameters.
    • If a parameter is defined as an integer and the parameter value contains alpha characters, an error will be returned to the caller before your API logic is called.
  • Required: Check if the parameter must be passed and must have a valid value.
    • When a parameter is defined as required and the parameter is not passed, an error will be returned to the caller before your API logic is called.
  • Example: An example of what the parameter value should be.
  • Allow Multiples: Check if the parameter should be an Array.
    • If a parameter is defined as an Array, but parameter value passed is not an array, an array will be created with that value as the only element, and then passed to your API logic
    • If a parameter is not defined as an Array, but parameter value is an array, the first valid value from that array will be passed to your API logic
  • Deprecated: Check this if you want to mark this parameter as deprecated or soon to be removed. The parameter will appear as deprecated in the Documenting Your APIs.
  • Description: Describes the parameter.  This field supports CommonMark.


6. API Options section: This is where you can access other API tools from the IDE.

  • OpenAPI Configuration:  This will open the openapi.json file where you can set up:
    • Your public API information, such as title, contact info, version, and license  → info-object
    • Security, such as authentication type and configuration  → security-scheme-object
  • API Documentation
  • API Dashboard
  • Find API File - If you do not know the API filename, then this is a great way to find the API



  • No labels