Resources Dual-Identifier System

In Payiano API, each resource is uniquely identifiable through distinct types of identifiers: the system-generated id and the developer-assigned reference_id. The id is a ULID automatically assigned by our system, ensuring each resource is uniquely identified. This simplifies the process of tracking, retrieving, and managing resources, as each one is given a distinct ULID identifier. This approach is widely used with multiple Payiano resources like Payment Links, Customers, Discounts, Taxes and many more.

On the other hand, the reference_id offers a more customizable approach. It is a string-based identifier that developers have the flexibility to assign to each resource. This alpha dash identifier accepts [A-Za-z0-9-_] regular expression, which is permitted to include alphabet lowercase, alphabet capitalcase, numbers from 0 to 9, hyphens and underscores, provides a significant advantage in scenarios where a more descriptive or specific identifier is necessary, such as integrating with external systems or maintaining internal naming conventions. It is crucial to ensure that each reference_id is unique, adhering to a strict format that only allows certain characters, thereby maintaining consistency and avoiding potential conflicts.

When it comes to API endpoint utilization, the choice of identifier influences the structure of the request. For operations like retrieving, updating, or deleting a specific resource, the API endpoints adapt to the type of identifier used. The endpoints take the form of /resources/{id} or /resources/{reference_id}, where {id} and {reference_id} are placeholders for the actual identifiers. Additionally, a query parameter identify_by might be included in the request, indicating whether the operation is being conducted using an id or a reference_id. This parameter plays a crucial role in guiding the system to correctly interpret and process the request based on the type of identifier provided.

Identify Resource By ID

Identify Resource By Reference ID

This dual-identifier system in our API design provides a high level of flexibility and efficiency. It caters to various operational needs and integration scenarios, allowing for a seamless and adaptable approach to resource management. Whether a resource is being identified through an automatically generated number for simplicity and uniformity, or a developer-assigned string for specific identification purposes, our API's approach ensures a robust, user-friendly, and versatile experience for managing diverse types of resources.

Consistent Structure

The dual-identifier consistency establishes predictable structure across the API. Regardless of the resource type, the format for accessing and manipulating data remains uniform. This consistency reduces the learning curve for developers, as they can apply the same principles and patterns when interacting with different resources. A structured approach also facilitates easier maintenance and scalability of the API, as new resources can be integrated seamlessly following the established pattern.

Ease of Use

By offering both a system-generated id and a developer-assigned reference_id, our API caters to different levels of technical proficiency and use-case scenarios. The id provides a straightforward, no-frills method of resource identification, ideal for quick development or when unique resource naming is not a priority. On the other hand, the reference_id allows for more descriptive, human-readable identifiers, making the API more intuitive and user-friendly, especially in scenarios where resources need to be referenced in a more recognizable or meaningful way.

This dual-identifier approach enhances the API's usability, adaptability, and scalability. It supports a wide range of applications and use cases, from simple internal tools to complex, integrated systems, offering a robust and developer-friendly solution for managing a variety of resources.