This help page is for users in Creator 6. Find your Creator version.

1. What Does This Page Cover?

2. Availability

Custom APIs:

1. Are available for creation only in the paid plans of Creator, whereas users in the trial plans can invoke them
2. Can only be created, authorized, and managed by the super admin and admins , while other users can access them
3. Are available in the United States (.com), Europe (.eu), India (.in), and Australia (.au) data centers
   

3. Overview

4. Custom APIs in Creator

Only super admin and admins can access the Custom API builder to create and manage custom APIs.

Note:

1. The number of API hits will be counted separately from the REST API hits in terms of pricing. 
2. Currently, you can only use the already configured  Deluge functions as custom APIs. This means you cannot invoke cloud functions written using Java and NodeJS scripts as a custom API. 
   
3. You cannot test your custom APIs in development environment since only the Deluge functions available in production environment can be exposed as a custom API. 

4.1 Functionalities of custom APIs in Creator

1. Custom APIs can help invoke operations that are otherwise possible only in Creator. For example, sending push notifications , fetching results from AI form fields and performing other data related actions, and so on.
2. Users can invoke Creator's own Deluge functions in your custom API instead of re-scripting a Deluge function or creating another custom API.
3. Create secure custom APIs by implementing authentication mechanisms to ensure that data access is controlled and secure, thereby reducing the risk of unauthorized access or data breaches.
4. Execute multiple logical operations through a single function execution.
5. Analyze and manage custom API logs as a single operation in one place when executing a huge operation through multiple API calls or external scripts.

4.2 How are custom APIs built in Creator?

1. Custom API Builder : A secure and easy-to-build interface that helps build a ready-to-use custom API which facilitates data exchange between Creator and external systems. 
2. Deluge functions : Your existing Deluge functions can be invoked in custom APIs.

4.3 Components of a custom API in Creator

1. Basic inputs
2. Endpoint URL
3. User scope
4. Request
5. Function
6. Response

Basic inputs

While naming your custom API, it is essential to choose names for your custom APIs that are descriptive, memorable, and reflective of their functionality. 

Note: If an unauthorized user tries to invoke the custom API using the endpoint URL, a System Response (i.e. Creator's Response) will be displayed. 

Note: 

1. The endpoint URL must be copied and pasted in the required external platform to invoke the custom API.
   
2. When you edit the link name of your custom API, change its scope or authentication method, the endpoint URL preview will be automatically updated in the Custom API builder. However, you need to manually update the endpoint URL wherever it has been invoked. If you invoke the custom API without updating the endpoint URL, a system response (error) will be shown. 

Request

1. Request Methods
2. Authentication
3. User Scope
4. Content Type

Request Methods for Custom API

1. GET: This method lets you request and retrieve data from the specified endpoint URL. In a GET request, data is typically sent as query parameters appended to the end of the URL.
2. POST: This method lets you submit data to be processed to the specified endpoint URL. In a POST request, data is typically sent in the request body, often in formats like JSON or form data. Here, the data is not appended to the URL. 
3. PUT: This method is used to update or replace an existing resource or to create a new resource at the specified URL. 
4. DELETE : This method is used to remove or delete a specific resource from the server at a given URL.

Authentication

User Scope

Content Type

Note: You can select the content type only for POST and PUT methods.

1. Application/JSON: This content type can be chosen to indicate that the data in the API request is in JSON (JavaScript Object Notation) format. This tells the external service that the data in the request body is in JSON format, and it should be processed accordingly.

JSON is a widely used data-interchange format that is often used to represent data objects, arrays, and key-value pairs, and is both human-readable and machine-readable. It is commonly used for transmitting structured data between a client and a server, making it an ideal choice for API communication. 

1. Multipart/form-data: This content type is used in API requests to send binary or textual data, such as files, to an external service. In a multipart/form-data request, the data is split into multiple parts, with each part having its own content type and headers. This allows for the inclusion of not only the data itself, but also additional information like filenames, field names, and content types for each part. A boundary string is used to separate the parts within the request. This string is unique and is specified in the request headers to indicate where each part starts and ends.

Multipart/form-data is commonly used when creating API endpoints that allow users to upload files or when working with forms that include file upload fields. When a user submits your form that contains a file input field, the custom API when invoked generates a "multipart/form-data" request to send the data to the external server.

Note: 

1. Multipart/form-data can't have nested data like JSON, which means that it just contains separate "key value" pairs.
2. It can have multiple entries on one key, unlike JSON.

1. Key and Value: This type lets you pass input parameters to your API endpoint as a key-value pair, and can be used when you need to pass a small number of distinct, named parameters in your API request.
   

1. Entire JSON: This type lets you pass a complete and unstructured JSON object, including all necessary key-value pairs as a single argument. You can use this approach when handling webhook calls .
   

Sample Request:

1. {
2. "user":{
3. "id":12345,
4. "name":"Alisa",
5. "email":"alisa@zylker.com",
6. "age":28,
7. "address":{
8. "street":"123 Main St",
9. "city":"Anytown",
10. "country":"Zylkerland"
11. },
12. "orders":[
13. {
14. "order_id":1001,
15. "total_amount":75.50,
16. "status":"delivered"
17. },
18. {
19. "order_id":1002,
20. "total_amount":102.20,
21. "status":"pending"
22. }
23. ]
24. },
25. "status":"success",
26. "message":"User data retrieved successfully"
27. }

In the above example:

1. The JSON response contains various nested elements.
2. "user" contains information about a user, including their ID, name, email, age, address, and a list of orders.
3. "address" is a nested object within the user details, containing address-related information.
4. "orders" is an array containing multiple objects representing different orders made by the user, each with its own attributes like order ID, total amount, and status.
5. "status" and "message" provide additional information about the overall status of the API request/response.
   

When you choose Entire JSON for this custom API, ensure that you specify only one argument of string datatype here each key is associated with a specific value. 

Response

1. Standard response: This response will return standard status codes currently followed by Creator's REST APIs. When this option is chosen, a sample response will be displayed below.
   
   
2. Custom response: This response lets you define and specify a custom status code and respective response codes as per your requirements. 
   
   

1. You can specify up to 50 response codes for each status code.
2. When you specify custom codes, the return type of the chosen Deluge function to be invoked must be Map.
3. You must map the specified response codes to their descriptive messages in the Deluge function. 

Function

In the Actions tab, you can select the Creator application and the namespace that contains the Deluge function to be executed when the custom API is invoked. 

1. When you create a Deluge function, it is recommended that you specify an appropriate namespace and function. This'll make it easier to define the actions of your custom API.
   
2. It is recommended to exercise caution while including sensitive operation in your Deluge functions and ultimately giving access to specific users to invoke your custom API.

Summary

When you create a custom API and exit the page before saving it, the custom API will be saved as a draft.

API logs

1. The API logs will display the logs of the last 30 days by default and maximum up to the previous 60 days.
   
2. Only super admin and admins can view API hits i.e., users cannot view API hits.

Scopes to invoke custom API

Method	Scope
GET, POST, PUT, DELETE	Zohocreator.customapi.EXECUTE

5. See How It Works

1. To fetch the pickup addresses of staff, students, and non-teaching staff in all the areas covered before a strip starts.
2. To submit the students' attendance and average trip speed at the end of each trip.

1. Three Get Records API to fetch the addresses from three separate reports.
2. Two Add Records API to add details about the trip and mark that day's attendance as records.

6. Use Cases

1. Hospital management: Let's assume you own a clinic and created a Hospital Management application using Creator. You want to fetch vital information from medical devices (fitted with sensors) worn by your patients, so that doctors will be immediately notified, monitor their vitals, and provide medical assistance as required. You can configure a custom API that is invoked whenever an abnormal reading occurs (considering various vitals such as heart rate, blood pressure, oxygen levels, and so on), The device sends these details via API request as a mobile notification to the respective doctor based on their availability. The assigned doctor can be prompted with a pop-up form in Creator (for smaller emergencies) to send medical advice to the treating medical staff. The doctor can also choose if an appointment is required immediately and book the earliest one. The patient receives the prescribed medical advice along with the appointment details (if applicable), via the API response. This data can also be added to the Appointment Booking and Patient Details forms respectively.
2. Approval management: Let's assume that you have created a Project Management application using Creator. Your employees create proposal document in an external service, which need to be approved by you (admin). Additionally, you need to add a record in your Creator application every time a document is approved and maintain records of rejected documents. You can create a custom API which is invoked when a document is submitted from the external service for approval. This will trigger the approval workflow in Creator, which will initiate the process of approving the documents and change the status of the doc as "Approved". A record will be added in the Project Details report and Quote Details reports respectively. If a document is rejected, then the status of the document will be marked as "rejected" and a record will be subsequently added in the Project Details report and Document Feedback reports respectively.

7. Navigation Guide for Creation of Custom APIs

8. Points to Note

1. The link name of your custom API cannot contain special characters such as  !@#$%^&*.>.
   
2. The status codes in custom response can range from 100 to 599.
3. The response codes in custom response must be in the range from 1 to 9999 and cannot contain special characters such as  !@#$%^&*.>.
4. When you change the user scope of your custom API to Admins Only from Selective Users, all the users you've previously added will be removed. 
5. If you close the Custom API builder without saving, your changes will still be saved as a draft and you can continue editing them anytime from Microservices > Custom API > required custom API card.
6. When you invoke a disabled API, an empty response will be returned i.e., invoking a disabled API will produce a record in API logs but will not be registered as an API hit. 
7. Before you can delete a function used in your Custom API, you will have to remove the associated Custom API before deleting the respective function.

9. Limitations

1. In the Response tab, you can add upto 50 status codes.
2. Your custom response codes can contain only upto 4 digits.

10. Related Topics

1. Create and manage custom APIs
2. Rest APIs in Creator