202 lines
3.4 KiB
Markdown
202 lines
3.4 KiB
Markdown
# Identity Management API
|
||
|
||
A high-level overview of a RESTful API for managing individual customers, their online accounts, and authenticated sessions. The API follows the JSON:API specification (`application/vnd.api+json`) for all request and response payloads.
|
||
|
||
---
|
||
|
||
## Base URL
|
||
|
||
```
|
||
http://localhost:8080/v1
|
||
```
|
||
|
||
---
|
||
|
||
## Resources Overview
|
||
|
||
| Resource | Description |
|
||
| ------------------------ | ----------------------------------------------------- |
|
||
| `/individualCustomers` | Manage individual customer records |
|
||
| `/onlineAccounts` | Manage online account credentials and associations |
|
||
| `/authenticatedSessions` | Create and manage authenticated sessions for accounts |
|
||
|
||
---
|
||
|
||
## Content-Type Requirements
|
||
|
||
All **POST** and **PATCH** requests must include:
|
||
|
||
```
|
||
Content-Type: application/vnd.api+json
|
||
```
|
||
|
||
---
|
||
|
||
# Individual Customers
|
||
|
||
Operations under `/individualCustomers` allow clients to create, retrieve, update, and delete customer profiles.
|
||
|
||
## Create Individual Customer
|
||
|
||
**POST** `/individualCustomers`
|
||
|
||
Example request:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "individualCustomer",
|
||
"attributes": {
|
||
"firstName": "Jane",
|
||
"lastName": "Smith",
|
||
"emailAddress": "jane.smith@example.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Retrieve Customer
|
||
|
||
**GET** `/individualCustomers/{customerId}`
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "individualCustomer",
|
||
"id": "12345",
|
||
"attributes": {
|
||
"firstName": "Jane",
|
||
"lastName": "Smith",
|
||
"emailAddress": "jane.smith@example.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Update Customer
|
||
|
||
**PATCH** `/individualCustomers/{customerId}`
|
||
|
||
Example request:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "individualCustomer",
|
||
"id": "12345",
|
||
"attributes": {
|
||
"emailAddress": "new.email@example.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Customer
|
||
|
||
**DELETE** `/individualCustomers/{customerId}`
|
||
|
||
---
|
||
|
||
# Online Accounts
|
||
|
||
Represents login-capable accounts tied to customers.
|
||
|
||
## Create Online Account
|
||
|
||
**POST** `/onlineAccounts`
|
||
|
||
Example request:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "onlineAccount",
|
||
"attributes": {
|
||
"username": "jsmith",
|
||
"password": "MyPassword123"
|
||
},
|
||
"relationships": {
|
||
"individualCustomer": {
|
||
"data": { "type": "individualCustomer", "id": "12345" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Retrieve Online Account
|
||
|
||
**GET** `/onlineAccounts/{accountId}`
|
||
|
||
## Update Online Account Credentials
|
||
|
||
**PATCH** `/onlineAccounts/{accountId}`
|
||
|
||
Example:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "onlineAccount",
|
||
"id": "acct-789",
|
||
"attributes": {
|
||
"password": "NewSecurePassword456"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# Authenticated Sessions
|
||
|
||
Used to authenticate an online account and generate a session token.
|
||
|
||
## Create Authenticated Session
|
||
|
||
**POST** `/authenticatedSessions`
|
||
|
||
Example request:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "authenticatedSession",
|
||
"attributes": {
|
||
"username": "jsmith",
|
||
"password": "MyPassword123"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"type": "authenticatedSession",
|
||
"id": "session-001",
|
||
"attributes": {
|
||
"issuedAt": "2025-01-01T12:00:00Z",
|
||
"expiresAt": "2025-01-01T14:00:00Z",
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# License
|
||
|
||
Specify license information here.
|
||
|
||
---
|
||
|
||
# Acknowledgments
|
||
|
||
Document inspirations, contributors, or tools used in the API’s development.
|