Open API Specification 3.0.0 (OAS) for Zoho CRM APIs
Table of Contents
- Overview
- Why use the OpenAPI Specification?
- GitHub Repository Details
- Swagger API Hub
- How to Use the Zoho CRM OpenAPI Specification 3.0.0?
- Integrating with third-party Applications
Overview
An OpenAPI Specification (OAS) is a standardized way to describe RESTful APIs. It defines API structure, authentication methods, endpoints, request and response formats, in JSON or YAML.
Why use the Open API Specification 3.0.0?
The Open API Specification is designed to provide:
- API Endpoints: The request URL and HTTP methods are specified, along with the optional and mandatory parameters required to make an API call request. The response formats for all possible HTTP response codes are available.
- Authorization: Supports OAuth 2.0 authentication for secure access.
- Request and Response formats: Standardized request formats for GET, POST, PUT, and DELETE operations, detailed response schemas to explain returned data structures, and error handling guidelines to help developers debug API requests.
GitHub Repository Details
The OpenAPI Specification for Zoho CRM APIs is hosted on GitHub:
- The latest version of the OAS document in JSON format.
- Refer to the GitHub Repository where all OAS files have been hosted.
Note
- Zoho CRM's OAS files are designed generically to show the standard API endpoints, request/response structures, and HTTP methods, and do not contain any specific unique business logics.
- For example, in module-specific cases, each module requires different input data, and the OAS files such as records.json may not fully cover your application's specific business needs since they are designed generically. Developers need to plan and manually address gaps based on what suits your use case and integrate them with your applications.
- Each OAS file for Zoho CRM APIs includes its corresponding OAuth scope to access Zoho CRM resources. If a scope contains the {module_API_name} placeholder, which represents the module API name, replace it with your required module name. Use the GET - Modules Metadata API to list all available module API names in your organization.
- For example, ZohoCRM.modules.{module_API_name}.READ should be replaced with ZohoCRM.modules.Leads.READ.
Refer to the OAuth Scopes page to view all available scopes.
Swagger API Hub
There are many tools to access OAS files. Here, we have used Swagger's API hub to demonstrate how to make use of Open API Specification version 3.0.0 specification for Zoho CRM APIs.
How to Use the Zoho CRM OpenAPI Specification 3.0.0
All Zoho CRM APIs' functionalities, structures, and syntax in standardized formats are documented using OAS, and the OAS files are hosted on GitHub to help you integrate your business with Zoho CRM.
Follow the below steps to get started:
Go to Github > Open v8.0
You will see a list of OAS files for Zoho CRM APIs.Select an API resource that suits your business case.
Here, we have used the record.json file.Copy the raw link of the selected file.
Right-click on "Raw" and copy the link address.Go to Swagger's API Hub > Design > Import API (Import your existing API definitions to API Hub for Designs).
You will navigate to the "Import API" pop-up box. Paste the copied raw link in the "Path or URL" field and click "Import".- After successfully importing the JSON file, you will be taken to the "API Design Editor" or "API Definition" page, where you can view, define, edit, and document your API using Open API Specification (OAS).
Integrating with third-party Applications
- Use OpenAPI client generators to create SDKs in Python, Java, Node.js, etc.
- Zoho CRM's OAS files provide developers and third-party integrators with a clear reference for Zoho CRM APIs, minimizing misunderstandings and integration errors.
We have demonstrated a sample Python SDK to create and fetch records in a module. This is achieved using the create and fetch methods from the records.json OAS file via the Python SDK. Please note that except for the create and fetch methods, the rest of the code remains the same across all SDKs.
Open the records.json OAS file in Swagger API Hub, follow the below steps to generate a Python SDK using Zoho CRM’s OpenAPI Specification (OAS) files and integrate it with your application.
Generate Python SDK from OAS
- Open Swagger API Hub > Go to Codegen > Client SDK > Python.
- This will download a Python SDK zip file.
Set Up the Python SDK
- Unzip the downloaded SDK file.
- Download the Python runner (.py) file.
- Move the runner file into the unzipped Python SDK folder.
Configure Authentication
- Go to Github > Open v8.0 > Open the runner .py file.
- Replace the placeholders with your Client ID, Client Secret, and Refresh Token to authenticate API requests
Run the Python SDK
- Execute the runner .py file in your local IDE.
- Use the create and fetch methods from the records.json OAS file via the Python SDK to interact with Zoho CRM data.
Note
The authentication setup and execution process remain the same across all SDKs. You can refer to the GitHub v8.0 repository for more OAS sample files.