mirrors/easyappointments
1
0
Fork 1
mirror of https://github.com/alextselegidis/easyappointments.git synced 2024-11-28 10:53:40 +03:00
Code Issues Projects Releases Packages Wiki Activity

Updated the REST API based on the latest API changes

Browse source
This commit is contained in:
Alex Tselegidis 2021-11-06 16:51:15 +01:00
parent 2bab1494dc
commit 3422f06cc5
1 changed files with 96 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

166
docs/rest-api.md
View file

@ -6,7 +6,7 @@ Easy!Appointments offers a flexible REST API that will enables you to handle all
### Open API Specification (Swagger File) ### Open API Specification (Swagger File)
The project has a ready-made [swagger file](https://raw.githubusercontent.com/alextselegidis/easyappointments/master/swagger.yml) you can download and use in order to create your client. The project has a ready-made [OpenApi file](https://raw.githubusercontent.com/alextselegidis/easyappointments/master/openapi.yml) you can download and use in order to create your client.
This file can also be imported into Postman, so that you can quickly get started making requests towards your installation. This file can also be imported into Postman, so that you can quickly get started making requests towards your installation.
@ -14,7 +14,9 @@ You will find more information about Open API and Swagger on [swagger.io](https:
## Making Requests ## Making Requests
The new API (v1) supports [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) which means that you will have to send the "Authorization" header with every request you make. **Always use SSL/TLS when making requests to a production installation.** That way you can ensure that no passwords will be stolen during the requests. The API expects the username and password of an admin user. The API (v1) supports [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) which means that you will have to send the "Authorization" header with every request you make. **Always use SSL/TLS when making requests to a production installation.** That way you can ensure that no passwords will be stolen during the requests. The API expects the username and password of an administrator user.
Additionally you can configure your own API key in the settings page and pass it through as a Bearer Token with any of your requests.
The API follows the REST structure which means that the client can use various HTTP verbs in order to perform various operations to the resources. For example you should use a GET request for fetching resources, a POST for creating new and PUT for updating existing ones in the database. Finally a DELETE request will remove a resource from the system. The API follows the REST structure which means that the client can use various HTTP verbs in order to perform various operations to the resources. For example you should use a GET request for fetching resources, a POST for creating new and PUT for updating existing ones in the database. Finally a DELETE request will remove a resource from the system.
@ -54,9 +56,11 @@ If you need to get only specific values from each JSON resource provide the `fie
http://ea-installation/index.php/api/v1/appointments?fields=id,book,hash,notes http://ea-installation/index.php/api/v1/appointments?fields=id,book,hash,notes
``` ```
### Aggregate ### Aggregate (Deprecated)
Aggregate related data into result payload by providing the `aggregates` parameter. Aggregate related data into result payload by providing the `aggregates` parameter.
> Notice: this parameter only applies to appointments and will be removed in the future (use the `with` paramter instead).
``` ```
http://ea-installation/index.php/api/v1/appointments?aggregates http://ea-installation/index.php/api/v1/appointments?aggregates
@ -64,6 +68,16 @@ http://ea-installation/index.php/api/v1/appointments?aggregates
*This parameter is currently only available for appointment resources.* *This parameter is currently only available for appointment resources.*
### With
Attach resources to the response payload with this parameter.
```
http://ea-installation/index.php/api/v1/appointments?with=customer,service,provider
```
*This parameter is only available for resources that are related to other resources.*
### Expected Responses ### Expected Responses
Most of the times the API will return the complete requested data in a JSON string but there are some cases that the responses will contain a simple message like the following: Most of the times the API will return the complete requested data in a JSON string but there are some cases that the responses will contain a simple message like the following:
@ -134,12 +148,13 @@ You can also try the GET requests with your browser by navigating to the respect
"book": "2016-07-08 12:57:00", "book": "2016-07-08 12:57:00",
"start": "2016-07-08 18:00:00", "start": "2016-07-08 18:00:00",
"end": "2016-07-08 18:30:00", "end": "2016-07-08 18:30:00",
"hash": "asdf809a8sdf987a9d8f7", "hash": "apTWVbSvBJXR",
"notes": "These are some test notes.", "location": "Test Street 1A, 12345 Some State, Some Place"
"customerId": 56, "notes": "This is a test appointment.",
"providerId": 4, "serviceId": 1,
"serviceId": 7, "providerId": 2,
"googleCalendarId": 134 "customerId": 3,
"googleCalendarId": null
} }
``` ```
@ -157,10 +172,12 @@ You can also try the GET requests with your browser by navigating to the respect
"id": 1, "id": 1,
"book": "2016-07-08 12:57:00", "book": "2016-07-08 12:57:00",
"start": "2016-07-08 18:00:00", "start": "2016-07-08 18:00:00",
"end": "2016-07-08 18:30:00", "end": "2016-07-08 18:30:00",
"notes": "These are some test notes.", "hash": "apTWVbSvBJXR",
"providerId": 4, "location": "Test Street 1A, 12345 Some State, Some Place",
"googleCalendarId": 474 "notes": "This is a test unavailability.",
"providerId": 1,
"googleCalendarId": null
} }
``` ```
@ -175,15 +192,17 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 97, "id": 1,
"firstName": "John", "firstName": "John",
"lastName": "Doe", "lastName": "Doe",
"email": "john@doe.com", "email": "john@example.org",
"phone": "0123456789", "phone": "+10000000000",
"address": "Some Str. 123", "address": "Test Street 1A",
"city": "Some City", "city": "Some Place",
"zip": "12345", "zip": "12345",
"notes": "Test customer notes." "timezone": "UTC",
"language": "english",
"notes": "This is a test customer."
} }
``` ```
@ -198,12 +217,12 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 74, "id": 1,
"name": "Male Haircut", "name": "Test Service",
"duration": 60, "duration": 15,
"price": 10.00, "price": 0.00,
"currency": "Euro", "currency": "EUR",
"description": "Male haircut trends.", "description": "This is a test service.",
"availabilitiesType": "flexible", "availabilitiesType": "flexible",
"attendantsNumber": 1, "attendantsNumber": 1,
"categoryId": null "categoryId": null
@ -223,9 +242,9 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 5, "id": 1,
"name": "Test Category", "name": "Test Category",
"description": "This category includes test services" "description": "This is a test category."
} }
``` ```
@ -240,20 +259,22 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 143, "id": 1,
"firstName": "Chris", "firstName": "Jason",
"lastName": "Doe", "lastName": "Doe",
"email": "chris@doe.com", "email": "jason@example.org",
"mobile": "012345679-0", "mobile": "+10000000000",
"phone": "0123456789-1", "phone": "+10000000000",
"address": "Some Str. 123", "address": "Test Street 1A",
"city": "Some City", "city": "Some Place",
"state": "Some City", "state": "Some State",
"zip": "12345", "zip": "12345",
"notes": "Test admin notes.", "timezone": "UTC",
"language": "english",
"notes": "This is a test admin.",
"settings":{ "settings":{
"username": "chrisdoe", "username": "chrisdoe",
"password": "p@ssw0rd", "password": "Password@123",
"notifications": true, "notifications": true,
"calendarView": "default" "calendarView": "default"
} }
@ -273,31 +294,33 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 143, "id": 1,
"firstName": "Chloe", "firstName": "Chris",
"lastName": "Doe", "lastName": "Doe",
"email": "chloe@doe.com", "email": "chris@example.org",
"mobile": "012345679-0", "mobile": "+10000000000",
"phone": "0123456789-1", "phone": "+10000000000",
"address": "Some Str. 123", "address": "Test Street 1A",
"city": "Some City", "city": "Some Place",
"state": "Some State", "state": "Some State",
"zip": "12345", "zip": "12345",
"notes": "Test provider notes.", "timezone": "UTC",
"language": "english",
"notes": "This is a test provider.",
"services": [ "services": [
1, 1,
5, 5,
9 9
], ],
"settings":{ "settings":{
"username": "chloedoe", "username": "chrisdoe",
"password": "p@ssw0rd", "password": "Password@123",
"notifications":true, "notifications": true,
"googleSync":true, "googleSync": false,
"googleCalendar": "calendar-id", "googleCalendar": null,
"googleToken": "23897dfasdf7a98gas98d9", "googleToken": null,
"syncFutureDays":10, "syncFutureDays": 90,
"syncPastDays":10, "syncPastDays": 30,
"calendarView": "default", "calendarView": "default",
"workingPlan":{ "workingPlan":{
"monday":{ "monday":{
@ -320,7 +343,7 @@ You can also try the GET requests with your browser by navigating to the respect
} }
] ]
}, },
"wednesday":null, "wednesday": null,
"thursday":{ "thursday":{
"start": "09:00", "start": "09:00",
"end": "18:00", "end": "18:00",
@ -331,24 +354,24 @@ You can also try the GET requests with your browser by navigating to the respect
} }
] ]
}, },
"friday":{ "friday": {
"start": "09:00", "start": "09:00",
"end": "18:00", "end": "18:00",
"breaks":[ "breaks": [
{ {
"start": "14:30", "start": "14:30",
"end": "15:00" "end": "15:00"
} }
] ]
}, },
"saturday":null, "saturday": null,
"sunday":null "sunday": null
}, },
"workingPlanExceptions": { "workingPlanExceptions": {
"2020-01-01": { "2020-01-01": {
"start": "08:00", "start": "08:00",
"end": "20:00", "end": "20:00",
"breaks":[ "breaks": [
{ {
"start": "12:00", "start": "12:00",
"end": "14:00" "end": "14:00"
@ -373,23 +396,26 @@ You can also try the GET requests with your browser by navigating to the respect
``` ```
{ {
"id": 143, "id": 1,
"firstName": "Chris", "firstName": "Jessy",
"lastName": "Doe", "lastName": "Doe",
"email": "chris@doe.com", "email": "jessy@example.org",
"mobile": "012345679-0", "mobile": "+10000000000",
"phone": "0123456789-1", "phone": "+10000000000",
"address": "Some Str. 123", "address": "Test Street 1A",
"city": "Some City", "city": "Some Place",
"state": "Some State",
"zip": "12345", "zip": "12345",
"notes": "Test secretary notes.", "timezone": "UTC",
"language": "english",
"notes": "This is a test secretary.",
"providers": [ "providers": [
53, 53,
17 17
], ],
"settings":{ "settings":{
"username":"chrisdoe", "username":"jessydoe",
"password":"p@ssw0rd", "password":"Password@123",
"notifications": true, "notifications": true,
"calendarView": "default" "calendarView": "default"
} }