Editing API/Getting Started

= Getting Started =

The **Verofy API** is semi-RESTful.  
If you are not familiar with interacting with REST APIs, please review a short introduction first:  
[https://www.geeksforgeeks.org/rest-api-introduction/# REST API Introduction].

Note that this API does stray from RESTful design in some key places.

Nearly any language and environment with web access can interact with REST APIs, and the technology is well documented.  
For the purposes of this guide **Python 3.10** will be used for examples, as it is easy to understand and can be refactored to many other languages.

----

== API Structure ==

The API is implemented using **Yii Modules** to support multiple releases simultaneously.  
Every API call includes the API version as part of the endpoint URL to identify which release the client application interacts with.

A typical request structure looks like this:

<pre><api_url>/<version>/<model>/<id></pre>

Where:
* <code>&lt;api_url&gt;</code> is the base URL of the API (e.g. `https://www.example.com`)
* <code>&lt;version&gt;</code> is the API version (e.g. `v1`)
* <code>&lt;model&gt;</code> is the object type you are interacting with (e.g. `segments`)
* <code>&lt;id&gt;</code> is the object ID for actions that require a specific record

Different endpoints may require different HTTP request types (`GET`, `POST`, `PUT`, `DELETE`), and some share the same URL between multiple request types.  
For details, see [[API/Endpoint Documentation]].

----

== Models ==

The API provides a method for operating on **models**, where each model is a discrete unit of data.  
In RESTful terms, a model corresponds to an **object** or **record**.

The API distinguishes between two main types of models:

=== Data-Driven Models ===

These represent editable and relatable data for an application.  
They are accessed frequently and hold most of the meaningful information.

Examples include:
* `segments`
* `access-points`
* `projects`

When accessing these models:
* A **VIEW** endpoint retrieves an individual record.
* An **INDEX** endpoint retrieves a collection of records.

=== Enum-Like Models ===

These are similar to enumerations, managed in the database but used as static lookups.  
They relate an ID with a fixed option or name, and are consistent across all projects.

Because they are small and static, they are provided by the **References** endpoints:
* **References (VIEW)** — returns all entries for a specific enum-like model.
* **References (INDEX)** — returns a collection of all enum-like collections.

For more information, see [[API/Endpoints: Models]].

----

== Endpoints ==

Endpoints can generally be divided into three categories:

* **Data-Driven Endpoints** — The bulk of the API, operating on main models.
* **Reference Endpoints** — Used for enum-like lookups and static label retrieval.
* **Misc Endpoints** — Used for login, authentication, and general utility actions.

See [[API/Endpoint Documentation]] for details.

----

== Health Check ==

The **Health Check** endpoint is a simple way to verify that:
* The API service is online, and
* The client is connecting to the correct version.

There are two types of health checks:
* A global one (not tied to a version)
* Version-specific ones (e.g., `/v1/health-check`)

These allow clients to confirm which API versions are available and functioning.

----

== Connect to the API ==

=== Prerequisites (Optional: Python & Pip) ===

All guides, examples, and tutorials use **Python 3.10** for simplicity.  
Any language capable of sending and receiving JSON-formatted HTTP requests will work.

To install Python and Pip:

* [https://www.geeksforgeeks.org/how-to-install-python-on-windows/ Install Python (Windows)]
* [https://www.geeksforgeeks.org/how-to-install-pip-on-windows/ Install Pip (Windows)]
* [https://phoenixnap.com/kb/install-pip-debian-12 Install Pip (Debian)]

Then install the `requests` package via Pip: