Skip to content

Commit a160133

Browse files
sruthymathew123sruthymathew123
committed
clean up
1 parent e323ff8 commit a160133

File tree

1 file changed

+144
-116
lines changed

1 file changed

+144
-116
lines changed

‎README.md‎

Lines changed: 144 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,182 @@
1-
# OpenAPIClient-php
1+
# LORIS PHP API Client
22

3-
LORIS REST API for clinical data ingestion pipelines.
4-
Authentication via JWT - POST /login to get token, use as \"Bearer <token>\".
3+
PHP client for LORIS REST API. Authentication via JWT.
54

5+
## Installation
66

7-
For more information, please visit [https://github.com/aces/loris](https://github.com/aces/loris).
8-
9-
## Installation & Usage
7+
```bash
8+
composer require aces/loris-php-api-client
9+
```
1010

11-
### Requirements
11+
## Dynamic API Version
1212

13-
PHP 8.1 and later.
13+
```php
14+
<?php
15+
require_once __DIR__ . '/vendor/autoload.php';
1416

15-
### Composer
17+
use LORISClient\Configuration;
1618

17-
To install the bindings via [Composer](https://getcomposer.org/), add the following to `composer.json`:
19+
$baseUrl = 'https://your-loris.ca';
20+
$apiVersion = 'v0.0.4-dev'; // v0.0.3 | v0.0.3-dev | v0.0.4-dev | v0.0.4
1821

19-
```json
20-
{
21-
"repositories": [
22-
{
23-
"type": "vcs",
24-
"url": "https://github.com/aces/loris-php-api-client.git"
25-
}
26-
],
27-
"require": {
28-
"aces/loris-php-api-client": "*@dev"
29-
}
30-
}
22+
$config = Configuration::getDefaultConfiguration()
23+
->setHost("{$baseUrl}/api/{$apiVersion}");
3124
```
3225

33-
Then run `composer install`
26+
## Authentication API
3427

35-
### Manual Installation
28+
```php
29+
use LORISClient\Api\AuthenticationApi;
30+
use LORISClient\Model\LoginRequest;
31+
use GuzzleHttp\Client;
3632

37-
Download the files and include `autoload.php`:
33+
$authApi = new AuthenticationApi(new Client(), $config);
3834

39-
```php
40-
<?php
41-
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');
42-
```
35+
$response = $authApi->login(new LoginRequest([
36+
'username' => 'user',
37+
'password' => 'pass'
38+
]));
4339

44-
## Getting Started
40+
$config->setAccessToken($response->getToken());
41+
```
4542

46-
Please follow the [installation procedure](#installation--usage) and then run the following:
43+
## InstrumentManager API
4744

4845
```php
49-
<?php
50-
require_once(__DIR__ . '/vendor/autoload.php');
46+
use LORISClient\Api\InstrumentManagerApi;
47+
use SplFileObject;
5148

49+
$api = new InstrumentManagerApi(new Client(), $config);
5250

51+
// Install instrument (LINST or REDCap CSV)
52+
$api->installInstrument(new SplFileObject('instrument.linst'));
5353

54+
// Get expected CSV headers
55+
$headers = $api->getInstrumentDataHeaders('CREATE_SESSIONS', 'demographics');
5456

55-
$apiInstance = new LORISClient\Api\AuthenticationApi(
56-
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
57-
// This is optional, `GuzzleHttp\Client` will be used as default.
58-
new GuzzleHttp\Client()
57+
// Upload data - CREATE_SESSIONS (creates missing candidates/sessions)
58+
$result = $api->uploadInstrumentData(
59+
'CREATE_SESSIONS',
60+
'demographics',
61+
null,
62+
new SplFileObject('data.csv')
5963
);
60-
$loginRequest = new \LORISClient\LORISClient\Model\LoginRequest(); // \LORISClient\LORISClient\Model\LoginRequest
6164

62-
try {
63-
$result = $apiInstance->login($loginRequest);
64-
print_r($result);
65-
} catch (Exception $e) {
66-
echo 'Exception when calling AuthenticationApi->login: ', $e->getMessage(), PHP_EOL;
67-
}
65+
// Upload data - VALIDATE_SESSIONS (requires existing candidates/sessions)
66+
$result = $api->uploadInstrumentData(
67+
'VALIDATE_SESSIONS',
68+
'demographics',
69+
null,
70+
new SplFileObject('data.csv')
71+
);
6872

73+
// Check result
74+
if ($result->getSuccess()) {
75+
echo $result->getMessage();
76+
foreach ($result->getIdMapping() ?? [] as $map) {
77+
echo "{$map->getExtStudyId()} → {$map->getCandId()}\n";
78+
}
79+
}
6980
```
7081

71-
## API Endpoints
72-
73-
All URIs are relative to *https://demo.loris.ca/api/v0.0.4-dev*
74-
75-
Class | Method | HTTP request | Description
76-
------------ | ------------- | ------------- | -------------
77-
*AuthenticationApi* | [**login**](docs/Api/AuthenticationApi.md#login) | **POST** /login | Authenticate and obtain JWT token
78-
*CandidatesApi* | [**createCandidate**](docs/Api/CandidatesApi.md#createcandidate) | **POST** /candidates | Create a new candidate
79-
*CandidatesApi* | [**getCandidate**](docs/Api/CandidatesApi.md#getcandidate) | **GET** /candidates/{candid} | Get candidate details
80-
*CandidatesApi* | [**getCandidates**](docs/Api/CandidatesApi.md#getcandidates) | **GET** /candidates | Get list of candidates
81-
*InstrumentManagerApi* | [**getInstrumentDataHeaders**](docs/Api/InstrumentManagerApi.md#getinstrumentdataheaders) | **GET** /instrument_manager/instrument_data | Get expected CSV headers for instrument data ingestion
82-
*InstrumentManagerApi* | [**installInstrument**](docs/Api/InstrumentManagerApi.md#installinstrument) | **POST** /instrument_manager | Install instrument from LINST file or REDCap data dictionary
83-
*InstrumentManagerApi* | [**uploadInstrumentData**](docs/Api/InstrumentManagerApi.md#uploadinstrumentdata) | **POST** /instrument_manager/instrument_data | Bulk insert instrument data from CSV file
84-
*InstrumentsApi* | [**getInstrumentData**](docs/Api/InstrumentsApi.md#getinstrumentdata) | **GET** /candidates/{candid}/{visit}/instruments/{instrument} | Get instrument data for a candidate/visit
85-
*InstrumentsApi* | [**getVisitInstruments**](docs/Api/InstrumentsApi.md#getvisitinstruments) | **GET** /candidates/{candid}/{visit}/instruments | Get instruments for a visit
86-
*InstrumentsApi* | [**patchInstrumentData**](docs/Api/InstrumentsApi.md#patchinstrumentdata) | **PATCH** /candidates/{candid}/{visit}/instruments/{instrument} | Update instrument data (preserves unspecified fields)
87-
*InstrumentsApi* | [**putInstrumentData**](docs/Api/InstrumentsApi.md#putinstrumentdata) | **PUT** /candidates/{candid}/{visit}/instruments/{instrument} | Replace instrument data (nulls unspecified fields)
88-
*ProjectsApi* | [**getProject**](docs/Api/ProjectsApi.md#getproject) | **GET** /projects/{project} | Get project details including instruments
89-
*ProjectsApi* | [**getProjectInstruments**](docs/Api/ProjectsApi.md#getprojectinstruments) | **GET** /projects/{project}/instruments | Get instruments for a project
90-
*ProjectsApi* | [**getProjects**](docs/Api/ProjectsApi.md#getprojects) | **GET** /projects | Get list of projects
91-
*SitesApi* | [**getSites**](docs/Api/SitesApi.md#getsites) | **GET** /sites | Get list of sites
92-
*VisitsApi* | [**createVisit**](docs/Api/VisitsApi.md#createvisit) | **PUT** /candidates/{candid}/{visit} | Create a new visit/timepoint
93-
*VisitsApi* | [**getVisit**](docs/Api/VisitsApi.md#getvisit) | **GET** /candidates/{candid}/{visit} | Get visit details
82+
## API Reference
83+
84+
### AuthenticationApi
85+
| Method | HTTP | Endpoint | Description |
86+
|--------|------|----------|-------------|
87+
| `login()` | POST | `/login` | Get JWT token |
88+
89+
### InstrumentManagerApi
90+
| Method | HTTP | Endpoint | Description |
91+
|--------|------|----------|-------------|
92+
| `installInstrument()` | POST | `/instrument_manager` | Install LINST/REDCap instrument |
93+
| `getInstrumentDataHeaders()` | GET | `/instrument_manager/instrument_data` | Get expected CSV headers |
94+
| `uploadInstrumentData()` | POST | `/instrument_manager/instrument_data` | Bulk upload CSV data |
95+
96+
### CandidatesApi
97+
| Method | HTTP | Endpoint | Description |
98+
|--------|------|----------|-------------|
99+
| `getCandidates()` | GET | `/candidates` | List all candidates |
100+
| `getCandidate()` | GET | `/candidates/{candid}` | Get candidate details |
101+
| `createCandidate()` | POST | `/candidates` | Create new candidate |
102+
103+
### VisitsApi
104+
| Method | HTTP | Endpoint | Description |
105+
|--------|------|----------|-------------|
106+
| `getVisit()` | GET | `/candidates/{candid}/{visit}` | Get visit details |
107+
| `createVisit()` | PUT | `/candidates/{candid}/{visit}` | Create new visit |
108+
109+
### InstrumentsApi
110+
| Method | HTTP | Endpoint | Description |
111+
|--------|------|----------|-------------|
112+
| `getVisitInstruments()` | GET | `/candidates/{candid}/{visit}/instruments` | List visit instruments |
113+
| `getInstrumentData()` | GET | `/candidates/{candid}/{visit}/instruments/{instrument}` | Get instrument data |
114+
| `putInstrumentData()` | PUT | `/candidates/{candid}/{visit}/instruments/{instrument}` | Replace instrument data |
115+
| `patchInstrumentData()` | PATCH | `/candidates/{candid}/{visit}/instruments/{instrument}` | Update instrument data |
116+
117+
### ProjectsApi
118+
| Method | HTTP | Endpoint | Description |
119+
|--------|------|----------|-------------|
120+
| `getProjects()` | GET | `/projects` | List projects |
121+
| `getProject()` | GET | `/projects/{project}` | Get project details |
122+
| `getProjectInstruments()` | GET | `/projects/{project}/instruments` | List project instruments |
123+
124+
### SitesApi
125+
| Method | HTTP | Endpoint | Description |
126+
|--------|------|----------|-------------|
127+
| `getSites()` | GET | `/sites` | List sites |
94128

95129
## Models
96130

97-
- [CandidateCreateRequest](docs/Model/CandidateCreateRequest.md)
98-
- [CandidateCreateRequestCandidate](docs/Model/CandidateCreateRequestCandidate.md)
99-
- [CandidateObject](docs/Model/CandidateObject.md)
100-
- [CandidatesResponse](docs/Model/CandidatesResponse.md)
101-
- [ErrorResponse](docs/Model/ErrorResponse.md)
102-
- [IdMapping](docs/Model/IdMapping.md)
103-
- [InstrumentData](docs/Model/InstrumentData.md)
104-
- [InstrumentDataMeta](docs/Model/InstrumentDataMeta.md)
105-
- [InstrumentDataRequest](docs/Model/InstrumentDataRequest.md)
106-
- [InstrumentDataRequestMeta](docs/Model/InstrumentDataRequestMeta.md)
107-
- [InstrumentDataResponse](docs/Model/InstrumentDataResponse.md)
108-
- [InstrumentDataResponseMessage](docs/Model/InstrumentDataResponseMessage.md)
109-
- [InstrumentMeta](docs/Model/InstrumentMeta.md)
110-
- [InstrumentsResponse](docs/Model/InstrumentsResponse.md)
111-
- [LoginRequest](docs/Model/LoginRequest.md)
112-
- [LoginResponse](docs/Model/LoginResponse.md)
113-
- [ProjectResponse](docs/Model/ProjectResponse.md)
114-
- [ProjectResponseMeta](docs/Model/ProjectResponseMeta.md)
115-
- [ProjectsResponse](docs/Model/ProjectsResponse.md)
116-
- [Site](docs/Model/Site.md)
117-
- [SitesResponse](docs/Model/SitesResponse.md)
118-
- [StageObject](docs/Model/StageObject.md)
119-
- [SuccessResponse](docs/Model/SuccessResponse.md)
120-
- [VisitCreateRequest](docs/Model/VisitCreateRequest.md)
121-
- [VisitInstrumentsResponse](docs/Model/VisitInstrumentsResponse.md)
122-
- [VisitInstrumentsResponseMeta](docs/Model/VisitInstrumentsResponseMeta.md)
123-
- [VisitObject](docs/Model/VisitObject.md)
124-
- [VisitObjectMeta](docs/Model/VisitObjectMeta.md)
125-
- [VisitObjectStages](docs/Model/VisitObjectStages.md)
126-
127-
## Authorization
128-
129-
Authentication schemes defined for the API:
130-
### BearerAuth
131-
132-
- **Type**: Bearer authentication (JWT)
133-
134-
## Tests
135-
136-
To run the tests, use:
131+
### Request Models
132+
| Model | Usage |
133+
|-------|-------|
134+
| `LoginRequest` | Authentication credentials |
135+
| `CandidateCreateRequest` | New candidate data |
136+
| `VisitCreateRequest` | New visit data |
137+
| `InstrumentDataRequest` | Instrument data update |
138+
139+
### Response Models
140+
| Model | Usage |
141+
|-------|-------|
142+
| `LoginResponse` | JWT token |
143+
| `CandidateObject` | Candidate details |
144+
| `CandidatesResponse` | List of candidates |
145+
| `VisitObject` | Visit details |
146+
| `InstrumentData` | Instrument data (Meta + Data) |
147+
| `InstrumentDataResponse` | Bulk upload result (success, message, idMapping) |
148+
| `IdMapping` | PSCID → CandID mapping |
149+
| `ProjectResponse` | Project with instruments |
150+
| `SitesResponse` | List of sites |
151+
| `ErrorResponse` | Error message |
152+
| `SuccessResponse` | Success confirmation |
153+
154+
## Regenerate Client
137155

138156
```bash
139-
composer install
140-
vendor/bin/phpunit
157+
# Using Docker (recommended)
158+
USE_DOCKER=1 ./generate.sh
159+
160+
# Using local OpenAPI Generator
161+
./generate.sh
162+
163+
# Clean regenerate
164+
./generate.sh --clean
141165
```
142166

143-
## Author
167+
### generate.sh
144168

169+
The script:
170+
1. Reads `schema.yml` and `openapi-config.json`
171+
2. Generates PHP client to `lib/`
145172

173+
## Upload Actions
146174

147-
## About this package
175+
| Action | Behavior |
176+
|--------|----------|
177+
| `CREATE_SESSIONS` | Creates candidates/sessions if missing |
178+
| `VALIDATE_SESSIONS` | Fails if candidate/session doesn't exist |
148179

149-
This PHP package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
180+
---
150181

151-
- API version: `0.0.4-dev`
152-
- Package version: `0.0.4-dev`
153-
- Generator version: `7.17.0`
154-
- Build package: `org.openapitools.codegen.languages.PhpClientCodegen`
182+
[OpenAPI Generator](https://openapi-generator.tech)

0 commit comments

Comments
 (0)