Editing API/Endpoint Documentation

= Endpoint Documentation =

This page describes the available **Verofy API endpoints**, grouped by category.

== Categories ==
* [[#Miscellaneous Endpoints|Miscellaneous Endpoints]]
* [[#Reference Endpoints|Reference Endpoints]]

----

== Miscellaneous Endpoints ==

=== Health Check (MISC) ===

Check whether the API is accessible, or if a particular version of the API is available.

There are two variants of this endpoint:
* **Global Health Check** — verifies the API service as a whole.
* **Version Health Check** — verifies a specific API version.

Returns:
* **200: OK** — the service or version is available.
* **404: Not Found** — the requested service is unavailable.

==== Ex. 1: Service Health Check ====
<syntaxhighlight lang="python">
import requests

response = requests.get("https://www.example.com/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_service": "OK"} expected
</syntaxhighlight>

==== Ex. 2: Version Health Check ====
<syntaxhighlight lang="python">
import requests

response = requests.get("https://www.example.com/v1/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1": "OK"} expected
</syntaxhighlight>

----

=== Access Check (MISC) ===

Check whether authentication has been successful.  
Accepts either an **access-token** or an **API key**.

Returns:
* **200: OK** — authentication successful  
* **401: Unauthorized** — authentication failed  

==== Ex. 3: Failed Access Check ====
<syntaxhighlight lang="python">
import requests

response = requests.get("https://www.example.com/v1/access-check")
print(response.status_code)   # 401 expected
</syntaxhighlight>

==== Ex. 4: Successful Access Check ====
<syntaxhighlight lang="python">
import requests

headers = {
    "Authorization": "Bearer n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc"
}
response = requests.get(
    "https://www.example.com/v1/references/MapSegmentType",
    headers=headers
)

print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1_access": "OK"} expected
</syntaxhighlight>

----

=== Login (MISC) ===

Provide **user credentials** to retrieve a new **refresh-token**.  
Intended for user-facing clients.  

⚠️ **Never store raw user credentials in a client app** — always prompt the user on each login.

Returns:
* A **refresh-token** if credentials are valid  
* **401: Unauthorized** otherwise  

'''Do not send credentials without HTTPS!'''

==== Ex. 5: Get Refresh-Token with Login ====
<syntaxhighlight lang="python">
import requests
import getpass

# Don't hard-code or store user credentials! Always ask the user.
ident = {
    "email": getpass.getuser(),
    "password": getpass.getpass()
}

response = requests.post("https://www.example.com/v1/login", json=ident)

print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "first-name": "John",
#   "last-name": "Doe",
#   "refresh-token": "tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
# } expected
</syntaxhighlight>

----

=== Refresh Token (MISC) ===

Exchange a **refresh-token** for a **new refresh-token** and a **fresh access-token**.

Intended for user-facing clients.  
Clients should store both tokens for later use.

Notes:
* Refresh-tokens can be used only **once**
* Once used, they are **invalidated**
* Always store the **new** refresh-token from the response

Returns:
* **200: OK** — new tokens issued  
* **401: Unauthorized** — invalid or expired refresh-token  

==== Ex. 6: Get Access-Token with Refresh-Token ====
<syntaxhighlight lang="python">
import requests

# Use the "login" endpoint first to obtain a refresh-token
headers = {
    "Authorization": "Bearer tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
}

response = requests.get("https://www.example.com/v1/refresh-access", headers=headers)
print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "access-token": "n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc",
#   "refresh-token": "8b1w1sx5gfwgwg_new_refresh_token_qn2n7ed2f22bn5ed"
# } expected
</syntaxhighlight>

----

== Reference Endpoints ==

=== References (VIEW) ===

Retrieve the specified **complete collection of reference models** as a single resource.

Optional parameter:
* `hash` — if supplied, the server compares it to its own hash for the collection.
  * If hashes differ → returns the collection.
  * If hashes match → returns an empty response.
* If the `hash` parameter is omitted → the full collection is returned.

If a ref-type is invalid or removed on the server:
* **410: Gone** — client should remove local copies and stop requesting that ref-type.

Returns:
* The collection as a resource (if available)
* **410: Gone** if the ref-type no longer exists
* **401: Unauthorized** if access is denied

----

''Next:'' → [[API/Endpoints: Models]]