API Endpoint Functionalities

Generated Endpoint Workflow

The section describes the overall process of how categorize API endpoints are used to exchange data.

Sending a request to the Endpoint
The "client" (an application or a third-party system) sends an HTTP request to the endpoints. The request includes specific information (inputs).
- Example: Request for GetCategory
```
bash
	POST https://api.olfeo.com/v1/GetCategory
	content-Type : application/json
	{
		"url": "https://example.com"
	}
```
Processing inputs on the server
Once the endpoint receives a request, the server performs the following steps:
- Validation: The server checks the inputs (e.g, URL format, data lenght, expected data type),
- Transformation: If necessary, the inputs are transformed (e.g., URL normalization, removal of unnecessary characters),
- Business Logic: The server executes the logic associated with an endpoint, such as querying a database to determine the category of the given URL.
Sending a response to the client
The server sends back a structured response to the client. The response typically includes:
- Result Data: For example, the category associated with the URL.
- HTTP Status Codes: Indicating the request's outcome (e.g., 200 OK: Request was successful, 400 Bad Request: Invalid input, 500 Internal Server Error: Server-side error).
- Example: Response for GetCategory
```
	json
	{
		"url" : "https://example.com",
		"categories" : ["News", "Technology"]
	}
```

Learn more about Validation and Transformation of inputs

Validation is the process of ensuring that input data conforms to specific criteria or constraints before it is is processed by a system. This includes verifying the type, format, range, and size of the data to ensure it meets predefined rules. The goal is to ensure that only accurate and acceptable data (domains or IPs) are passed for further processing.

On the other hand, transformation refers to modifying or formatting input data so it aligns with the internal requirements of the system. This process can involve normalizing, adapting data to fit the needs.

Together, validation and transformation ensure input data is ready for processing, thereby reducing risks like vulnerabilities, errors or incorrect outputs.

Practical examples: Validation and Transformation of inputs

This section presents a table of examples showcasing how the system validates and transforms input data under various constraints.

Handling validation of inputs
- Lenght < 255 characters
  This validation ensures that the total length of a domain, including all its labels and separating dots, does not exceed 255 characters, which is the maximum allowed by the DNS protocol. The length limit is critical because it ensures that domain names remain manageable and resolvable across all DNS systems. For example, a domain like [wignlgwivylydhyragcqbzoxmxhpdarbbjwaxtggyfjuhktsmqyorjqahtlquwa.slcrpmzbarcmkjjjjihyhxnanbqaplntfrlamqgftmogfmqqhghkjxvfsdedkkh.gtlmneotooiwyjzupughmlxdobqbijquczinncjclaugmdkawplwbzpvdajrjqs.hahkflakcoxoncnkenhrhihhmbkpcdubhksbburkmbnrztgmrkknacgzsxhogfo.com] exceeds the allowed length and would be rejected by the system. The API responds with an error such as code: invalid_argument, message : domain length > 255`. This check is necessary to maintain compliance with DNS standards and to prevent excessively long domain names from breaking the system.
- Each label does not exceed 63 characters
  Each label within a domain (a segment of the domain name between dots, such as 'www', 'example', or 'com') must not exceed 63 characters. This is another DNS protocol requirement to ensure compatibility and reliability. For instance, the domain[mrqzetqtkivbzngbhoiaznktkbcmceemtbtumtsjyapi.com] has one label (i.e., mrqzetqtkivbzngbhoiaznktkbcmceemtbtumtsjyapi) that exceeds this limit. As a result, the system rejects the domain and returns an error like code: invalid_argument, message : idna: invalid label. This step guarantees that all domain components are well-formed and valid.
Handling transformation of inputs
- Lenght <= 253 without the trailing dot
  This transformation ensures that domains are truncated to a maximum length of 253 characters after removing any trailing dots. A trailing dot, such as in [flbydawyqbxacdhfiknlpwwdxaswuxuraioxskrbzvijszsijbldlygxcnvcrze.lgrxgpunojzrftspdquunnuzdspfgeifkipjmjeueiysysgsuufzklxowenaibh.sxruagbsvyjcprdxrmbbnanwlkitgksqkabzrztlblfbrtztytipqybqlzjmrou.vpovlkqbvrkkjdxrbqisagqoylptyisamqupxzlravlhbeviyypsckxfgusgp.], indicates the root of the DNS hierarchy but is often unnecessary for most practical purposes. The transformation removes the dot, leaving [flbydawyqbxacdhfiknlpwwdxaswuxuraioxskrbzvijszsijbldlygxcnvcrze.lgrxgpunojzrftspdquunnuzdspfgeifkipjmjeueiysysgsuufzklxowenaibh.sxruagbsvyjcprdxrmbbnanwlkitgksqkabzrztlblfbrtztytipqybqlzjmrou.vpovlkqbvrkkjdxrbqisagqoylptyisamqupxzlravlhbeviyypsckxfgusgp], and checks that the domain length remains under 253 characters. This ensures that the domain remains usable while adhering to the length limits required by DNS.
- IDNA Decomposition
  Internationalized domain names (IDNs) allow the use of non-ASCII characters, such as accented letters or characters from non-Latin alphabets. Since DNS systems only support ASCII characters, IDNs must be converted in Punycode, a standardized ASCII representation. This transformation ensures that domains remain valid while being compatible with DNS resolution. For example, the domain [société.com] (which includes the "é" character) is transformed into [xn--socit-esab.com]. This process ensures that the domain can be processed by DNS servers while retaining its original meaning and intent, making it possible to handle multilingual domains effectively.
- Removal of square brackets from IPv6 addresses
  IPv6 addresses are sometimes enclosed in brackets, such as [2001:db8::1], to differentiate them from regular domain names in contexts like URLs. While the brackets are useful for certain contexts, they are unnecessary for DNS processing. This transformation removes the brackets, leaving 2001:db8::1. By doing so, the system ensures consistency in IPv6 address formatting and prepares the input for further processing or resolution.
- Removal of the trailing dot from the domain
  Fully qualified domain names (FQDNs) sometimes include a trailing dot to explicitly indicate the DNS root. For example, [www.olfeo.com.] includes a trailing dot. While technically valid, the dot is unnecessary for most use cases. This transformation removes it, resulting in [www.olfeo.com]. The removal simplifies domain handling and ensures a consistent format across the system while preserving the meaning of the domain.
- Extraction of the host if the URL is provided
  When a complete URL or a prefixed host representation is provided, this transformation extracts the host portion, which is the domain name itself. For example, from the input [https://olfeo.com/path?query=123], the system extracts [olfeo.com], discarding the protocol (https://), path (/path), and query string (?query=123). This step is important for scenarios where only the domain name is needed, such as for DNS lookups or host-specific operations.
- URL concatenation
  This transformation combines different parts of a URL, such as the base path, additional segments, and query parameters, into a complete and functional URL. For instance, if the domain ends '/foo' with and another part adds '/bar', the system combines them into '/foobar' to create a single, cohesive path. This ensures URLs are properly constructed for use in HTTP requests, API calls, or redirects, reducing the risk of errors from malformed URLs.
- Adding a / at the beginning of the URL if missing
  To standardize paths, this transformation ensures that a leading slash is added to URLs that lack one. For example, if the input URL is, [olfeo.com], url: 'foobar', it is transformed into [olfeo.com], url: '/foobar'. Adding a leading slash makes the path consistent with URL formatting conventions and prevents errors caused by missing slashes during concatenation or routing operations.

Olfeo OEM documentation