Prerequisites:

• Download the module file (usually a .zip file) from a trusted source like https://ekika.co OR Odoo App Store
• Ensure your Odoo 17 instance is up and running.
• Have administrative access to your Odoo instance (self-hosted or odoo.sh).

How to install Odoo Apps?

• Download the Module:

  • Locate the appropriate module for your needs on a trusted repository like the Odoo Apps Store (https://apps.odoo.com/apps) or from our website https://ekika.co .
  • Download the module file (typically a .zip file).
  

• Extract the Module Files:

  • Use a decompression tool like WinRAR or 7-Zip to extract the contents of the downloaded .zip file. This will create a folder containing the module's files.

• Place the Module in the Addons Path (Custom Addons Recommended or Commit to your Version Control system i.e. git):

  • Recommended: Create a dedicated custom_addons repository/folder similar to your main Odoo addons directory. This keeps official and custom modules organized.
  • Odoo.sh: If using Odoo.sh, upload the extracted folder to the ~/src/user/ directory OR recommended to commit in custom addons.
  • Direct Odoo Installation: For a self-hosted Odoo instance, copy or move the extracted folder to the addons directory within your Odoo project directory using git recommended.

• Using Git for Version Control (Optional but Recommended):

  • If the module is available in a Git repository, consider using Git for version control:
  • Navigate to your custom_addons directory using the terminal.
  • Clone the repository using the git clone command and the provided URL.
  • This approach allows you to track changes, collaborate with others, and easily update the module.
  • We manage our api addons for customers for regular important updates too. We strongly recommend you to use direct source to keep you up to date with changes. Send us email after purchase on hello@ekika.co to get access to our repository.
  

• Restart Your Odoo Service:

  • For changes to take effect, restart your Odoo service. The specific method may vary depending on your installation method (manual, Docker, service manager like systemd). Refer to your Odoo documentation for detailed instructions.

• Open Odoo in Your Browser and Log In with Admin Access:

  • Access your Odoo instance in a web browser (usually http://localhost:8069) in local system.
  • Use your administrator credentials to log in.
  

• Activate Developer Mode:

  • Developer mode is typically required for installing newly added addons.
  • Go to Settings (usually a gear icon in the main menu).
  • Scroll to bottom in settings.
  • Click the link to activate Developer mode or add query-parameter in URL: &debug=1 after the /web and before # in the url.
  

• Update the Module List:

  • Go to the Apps section in your Odoo instance.
  • Click on Update Apps List. This ensures Odoo detects the newly added module from your addons path in configuration file.
  

• Find and Install the "api_framework" App:

  • If the module you're installing depends on the api_framework app, search for it in the Apps section. (Optional in case if you are installing our free api helper modules)
  • If it's not already installed, click Install to proceed.
  

• Configure API Permissions (Required to grant permission to API manager or User):

• Verify Installation and Access:

  • Depending on the module, you might need to access specific menus or functionalities to verify successful installation. If you can see main API menu you have enough access to get started. You require administrative access as api containes user permission and user and permission management require user record access.

• Additional Tips:

  • Backup: It's always recommended to back up your Odoo database before installing new modules, especially custom ones. Because we do not know you environment and what are things attached with module installation procedure.
  • Custom Modules and Security: Exercise caution when installing custom modules from untrusted sources. They could introduce security vulnerabilities or may cause weired behaviour in your environment.

What is API Authentication?

API authentication is the process of verifying the identity of a client or user who is making an API request. It ensures that only authorized users or systems are granted access to the API's resources or functionality. Authentication mechanisms typically involve the exchange of credentials or tokens between the client and the API server to establish trust and validate the client's identity. This process helps to maintain the security and integrity of the API by preventing unauthorized access and misuse of its services. There are various authentication methods commonly used in APIs:

• API-Key Based
• Basic Authentication
• User Credentials
• OAuth2

Here, we explain every API Authentication in brief:

• API-Key Based: A simple method where clients include a unique key in their requests to authenticate themselves. These keys are passed in the request headers. The most popular choice for including API keys in headers "x-api-key" is a custom header convention for passing your API key. The API key must be sent with every request.
• API Key is located on the API listing section and inside that request, you can add your API Key Manually or Auto Generated.
• Then you have to add the API Key to your postman's headers in x-api-key's value field.


• Basic Authentication: In this method the client or user sends a request. The request header contains the Base64-encoded username and password, seprated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content.


• User Credentials: In this method the client provides its username and password to the API server as proof of identity. The server then verifies these credentials against its records to authenticate the client. If the provided credentials match those stored in the server's database, the client is granted access to the API's resources or services.

• OAuth2: OAuth2 stands for "Open Authorization 2.0". It is the second version of the OAuth protocol, which is an open standard for access delegation commonly used for API authentication and authorization. OAuth 2.0 is a widely used authorization framework that allows applications to securely access resources on behalf of users without needing their credentials. It's commonly used for API authentication in web and mobile applications. OAuth 2.0 uses Access Tokens. An Access Token is a piece of data that represents the authorization to access resources on behalf of the end-user.

JSON API

Introduction

JSON API is a specification for building APIs (Application Programming Interfaces) in JSON format. It provides guidelines for how client applications can request and receive data from a server.

How It Works

JSON API works by defining a specific structure for API requests and responses, allowing for consistency and ease of use. Here's how it works:

Request:

1. Endpoint: Clients make requests to specific endpoints (URLs) on the server to retrieve or manipulate resources. For example, a client might request a list of articles from the “/articles” endpoint.
2. HTTP Methods: JSON API uses standard HTTP methods like GET, POST, PATCH, and DELETE for different operations. GET is used to retrieve data, POST to create new resources, PATCH to update existing resources, and DELETE to remove resources.
3. Parameters: Clients can include query parameters in the request URL to specify filtering, sorting, pagination, sparse fieldsets, or include related resources. For instance, clients can request only specific fields of a resource, or request related data to be included in the response.

• Learn more about JSON API from here.
• Also, Checkout https://jsonapi.org/ for official documentation of JSON API.

Create JSON API

• First we have to go into our API listiing section where all the APIs are listed. Then click New to create new API showed in image below.

• Add the Name, Endpoint, Authentication, Access Control, & generate the API Key for the perticular user you want to give access to. Note: If you are not able to generate the API Key then make sure to do this following steps: Go to Configuration >> Settings >> API Key Settings >> Select Auto.
• Copy the Endpoint URL and add it to the postman request section field. After that you have to add you model name (E.G res.partner). After that you can write your query by simply adding ? after the model name.
• Add this API Key to Get Requests Header, inside key field enter X-API-Key and add the API Key in value field shown in image below.

• Add the query parameters as you required.

• After adding query parameers you can simply send the request by clicking send button.
• You will get this type of response shown in image below.

Checkout below module for more information related to JSON API.

GraphQL API

Introduction

GraphQL is a query language for APIs and a runtime for executing those queries with existing data.

1. Declarative Data Fetching: GraphQL allows clients to request only the data they need and nothing more. Clients can specify the shape and structure of the response, reducing the over-fetching and under-fetching of data that often occurs in REST APIs.

2. Hierarchical Structure: GraphQL queries have a hierarchical structure, mirroring the shape of the response data. Clients can request nested fields, and the server responds with a JSON object that matches the requested structure.

How It Works

In GraphQL, queries and mutations are two types of operations used to interact with the API:

1. Query Operation: A query in GraphQL is used to read or fetch data from the server. Clients can specify exactly what data they need, and the server will return only the requested data, no more and no less. Queries are similar to GET requests in REST APIs.
2. Mutation Operation: A mutation in GraphQL is used to modify data on the server. Mutations are similar to POST, PUT, PATCH, or DELETE requests in REST APIs. Mutations can be used for creating, updating, or deleting records.

• Learn more about GraphQl API from here.
• Also, Checkout https://graphql.org/learn/ for official documentation of GraphQL API.

Create GraphQL API

• First we have to go into our API listiing section where all the APIs are listed. Then click New to create new API showed in image below.

• Add the Name, Endpoint, Authentication, Access Control, & generate the API Key for the perticular user you want to give access to. Note: If you are not able to generate the API Key then make sure to do this following steps: Go to Configuration >> Settings >> API Key Settings >> Select Auto.
• Copy the Endpoint URL and add it to the postman request section field. You don't have to add any query in this field.
• Add this API Key to Post Requests Header, inside key field enter X-API-Key and add the API Key in value field shown in image below.

• Write the query as you required.

• After adding query you can simply send the request by clicking send button.
• You will get this type of response shown in image below.

Checkout below module for more information related to GraphQL API.

API-Key Authentication

This module serves as a fundamental building block within the API Framework. To implement API-key based authentication in your API configuration system, it is essential to integrate this module. Keep in mind that this module is not designed to function independently; it relies on the API Framework Base (api_framework_base) as its foundation to seamlessly operate with various API authentication mechanisms.

Auth API-Key Introduction

API-Key authentication is a simple and effective way to secure your API endpoints by requiring clients to include an API key in the request headers. This authentication method ensures that only authorized users can access your API resources.

How It Works

When making a request to an API endpoint that requires authentication, clients must include an X-API-Key header in the HTTP request. The value of this header should be the API key provided to the client by the API provider.

• Learn more about Auth API-Key from here.

Api OAuth2

OAuth2 stands for "Open Authorization 2.0". It is the second version of the OAuth protocol, which is an open standard for access delegation commonly used for API authentication and authorization. OAuth 2.0 is a widely used authorization framework that allows applications to securely access resources on behalf of users without needing their credentials. It's commonly used for API authentication in web and mobile applications. OAuth 2.0 uses Access Tokens. An Access Token is a piece of data that represents the authorization to access resources on behalf of the end-user.

Introduction

This module include authorization-code-grant flow of OAuth2 for API.

How It Works

Auhtorization and Token Related Steps:

• First, client register redirect-uri, which is provided in api record form, to its respected provider.
• Client has to made request to "/<api>/oauth2/provider/authorize" with its client_id in request-body(json), which returns authorization_url in json-body from response
• When client use this authorization_url, client has to authorize with its respected user, after successful authorization server returns token information, which includes:
• access_token, refresh_token, expires_in, expires_at, scope, token_type, id_token. Note: this differs from provider
• db, login
• If client wants to refresh the token & get access-token then made request to "/<api>/oauth2/token" with its client-id, client-user-identity in request-body(json), which return new token related information
• If client wants to revoke the token then made request to "/<api>/oauth2/revoke" with its client-id, client-user-identity in request-body(json), which revoke the token from authorization server and also delete the client api user record.

API Resource Access Steps:

• When client want fetch api data using oauth2 method, made http-request using header: Authorization: Bearer access_token_value
• If access_token in valid then it return response data. and if access_token invalid then client has to refresh the token or authorize the user again.

For More Details

Python Request Examples:

1. Client Authorization:

import requests
import json

url = "https://easyapi.ekika.app/jsonapiext/oauth2/provider/authorize"

payload = json.dumps({
  "client_id": "YOUR_CLIENT_ID",
  "client_user_identity": "YOUR_UNIQUE_CLIENT_IDENTITY"
})

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

2. Refresh Token:

import requests
import json

url = "https://easyapi.ekika.app/jsonapiext/oauth2/token"

payload = json.dumps({
  "client_id": "YOUR_CLIENT_ID",
  "client_user_identity": "YOUR_UNIQUE_CLIENT_IDENTITY"
})

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

3. Revoke Token:

import requests
import json

url = "https://easyapi.ekika.app/jsonapiext/oauth2/revoke"

payload = json.dumps({
  "client_id": "YOUR_CLIENT_ID",
  "client_user_identity": "YOUR_UNIQUE_CLIENT_IDENTITY"
})

headers = {
  'Content-Type''application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

• Learn more about Api Oauth2 from here.

Basic Authentication

Introduction

HTTP Basic Authentication is a simple authentication scheme built into the HTTP protocol. It is based on challenge-response mechanism and is widely used for securing web applications and APIs. This document provides an overview of HTTP Basic Authentication, how it works, and examples of how to implement it.

Format of Authorization Header

The Authorization header for HTTP Basic Authentication is constructed as follows:

Authorization: Basic base64(username:password)

The base64(username:password) is the base64 encoding of the concatenation of the username and password, separated by a colon (:).

Headers

Example

Here's an example using cURL:

curl -X GET "https://api.example.com/resource" -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

Here's an example using Python:

import requests
    
api_url = 'https://api.example.com/resource'

# Make an authenticated GET request
headers = {
    'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
}

response = requests.get(api_url, headers=headers)

• Learn more about Auth Basic from here.
• Also, Checkout RFC 7617 for official documentation of "Basic" HTTP authentication.

User Authentication

Introduction

The user authentication API requests using username and password headers. By following these instructions, developers can ensure secure communication with the API server.

How It Works

The user authentication works by sending a username and password in the HTTP request header. The server challenges the client with a 401 Unauthorized response, indicating that authentication is required. The client then includes the username and password in the Authorization header of subsequent requests.

Headers

Example

Here's an example using cURL:

curl -X GET -H "username: your-username" -H "password: your-password" https://api.example.com/resource

Here's an example using Python:

import requests
    
api_url = 'https://api.example.com/resource'

# Make an authenticated GET request
headers = {
    'username': 'your-username',
    'password': 'your-password',
}

response = requests.get(api_url, headers=headers)

• Learn more about Auth User Credential from here.