☁️Data Provider API Design

Conektto is one of very few platforms that enables product managers to connect their data source and build APIs easily without knowledge of complex JSON or YAML.

Conektto supports most of the commonly used relational database like SQL Server, Postgres and MySQL.

With Conektto's design studio, you can securely connect to your database server hosted on cloud or a VM with external IP, scan schema, order and sequence, make your entities available as drag/drop into the design studio.

Before you design, make sure to:

Define the purpose and scope of the API: Determine the specific data or functionality that the API will provide and how it will be used.
Identify the data sources: Determine where the data will come from and how it will be collected. Identify host credentials and/or SSL certificates for connecting to the database.
Define the API structure and endpoint: Decide on the structure of the API, including the endpoint and the data fields that will be provided.
Validate and define business logic: relationships/joins and filter conditions
Publish the API documentation: Publish the API design that generates Open API spec, Java Spring boot code, .NET EF code, Apgiee endpoint, API Test workspace, and the ability to push to your GitHub workspace.
Test the API: Test the API to ensure that it functions as expected and that the data is accurate.
Release the API to the public or specific users: Make the API available for use by the intended audience.

Create API Project

✅Click "Create New API" and Click "Design Studio"

Connect Database

✅Click "Next" to connect your database

Select Database Server Type, and provide host credentials for the desired database under design. You may also choose to connect to your database through SSL. You are required to upload your SSL certificates if you choose to do so. Click "Test" to test the database connection. If you have trouble in connecting the database, check "Support" section for additional details.

Invite Collaborators

✅Click on "Invite Collaborators"

APIs are no good designed, built or tested in silos. Invite your desired users or stakeholders that you would like to share the API Design project by providing their email id. The respective users will get an email with a link for collaboration.

✅Click on "Done" to continue with collaborators or "Skip for now" to add collaborators later

✅ Conektto's engine now scans your API schema, your database, runs our patent pending NLP matching process before loading your API test studio designer.

⚠️This process may take several minutes based on the complexity of your schema, database and volume of data.

Examine your data tables, columns, and all entities

✅ After successful scanning and matching, you will be presented with Design Studio, you will notice all your tables and columns from your database schema available.

ℹ️You can navigate between tables view and respective columns view by using the navigation as illsutrated :

Create custom parameters

✅Create custom paramters if you would like to define groups for your entities. If your entities are direct attributes, you can drag and drop the enities in the contract designer and start renaming. Refer the API Standards and Governancefor supported naming conventions.

Referfor step by step instructions on how to use the interface for parameter creation.

Create your API contracts - Rest endpoints, Operations, and payload structure

✅Create Resource & add Path

Resource is the primary data representation. Having a consistent and robust REST resource naming strategy – will prove one of the best design decisions for consumability, maintenanbility, avoid API sprawl and API lineage.

A resource can be a singleton or a collection.

URI = resources + Path

For example, “accounts” is a collection resource and “account” is a singleton resource (in a customer domain).

Similarly, a singleton resource “department” inside the path resource “departments” can be identified as follows: “/accounts/{accountId}/departments/{departmentId}“. REST APIs use Uniform Resource Identifiers (URIs) to address resources. Product Managers and API designers should consider creating URIs that convey a REST API’s resource model to the end users or consumers of the API. When resources are named well, it makes the API intuitive, aligns with product strategy and easy to use.

URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties that verbs do not have – similarly, resources have attributes. Some examples of a resource are consumers of your API, users of your product, user accounts or account groups, etc. ⚠️Prevent using upper case, underscores, actual CRUD verb, query component, etc.

👍Using (-) hyphens improves readability of the resources / URI

HTTP Method / Operations

REST APIs enable product managers and API teams to build web applications having all possible CRUD (create, retrieve, update, delete) operations.

REST guidelines suggest using a specific HTTP method on a particular type of call made to the server (though technically it is possible to violate this guideline, yet it is highly discouraged).

ℹ️GET, PUT, POST, DELETE are some of the most commonly used HTTP operations.

To simplify it:

GET - to retrieve data and not for making changes to state

POST - to create new subordinate resources, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table.

PUT - to update an existing resource (if the resource does not exist, then API may decide to create a new resource or not).

DELETE - to delete a resource or data from the collections

✅Drag and drop desired columns from the table or entire table structure as a group by themselves or under parameter.

✅Drag and drop columns or parameters as desired based on your API contract structure.

✅Click Response tab, drag and drop desired tables or columns in the response body. By default, 200 for success response. If you would like your API to respond with user with proper errors and validations, user status codes like 4xx or 5xx.

👍Always use renowned models as guiding principles like Richardson Maturity Model as illustrated below.

Examine Schema and Simulate payload

✅Visually examine the Schema

Inspect the operations pre-loaded from the Schema and examine for correctness and completeness of RestAPI operations and contracts.

✅Visually simulate the payload

ℹ️Click "SEND" to simulate the request, response payload structure.

Pre-Publish: Validations and Mapping

After confirming the contracts, click "Publish"

Publish action prepares your API contracts, schema and entities selected for validation against OpenAPI standards as well as mapping complex business logic.

✅ Validations

Conektto assures thorough validation of API standards. The following are various levels of validations if not addressed, your publish would fail:

Naming conventions
Descriptions, optional and mandatory parameters
Correctness of Operations and components
Completeness of Operations Status codes
Bare minimum structure of a RestAPI contract (Header, Request Body, Response Body)

✅ Business logic: Relationship, joins and filters

⚠️Conektto allows users to validate existing entity relationships. Where the database is not normalized, you are able to define custom mapping between the entities. Additionally users can create Filter conditions for the API.

✔️Derived Entity Maps - preloaded maps based on database schema scanning

✔️User Defined Entity Maps - custom maps defined by user

✔️Filters - custom filter conditions annotated by user