README.md in supersaas-api-client-1.1.1 vs README.md in supersaas-api-client-2.0.0

- old
+ new

@@ -1,36 +1,32 @@ # SuperSaaS Ruby API Client -Online bookings/appointments/calendars in Ruby using the SuperSaaS scheduling platform - https://supersaas.com +Manage appointments, users, and other object on the [SuperSaaS appointment scheduling](https://www.supersaas.com/) platform in Ruby. -The SuperSaaS API provides services that can be used to add online booking and scheduling functionality to an existing website or CRM software. +The SuperSaaS API provides endpoints that can be used to read or update information from your SuperSaaS account. +This can be useful to build an integration with back-end system or to extract information to generate reports. ## Prerequisites 1. [Register for a (free) SuperSaaS account](https://www.supersaas.com/accounts/new), and -2. get your account name and API key on the [Account Info](https://www.supersaas.com/accounts/edit) page. +2. Get your account name and API key on the [Account Info](https://www.supersaas.com/accounts/edit) page. -##### Dependencies +### Dependencies -Ruby 1.9 or greater. +No external dependencies. Only the `json` and `net/http` gems from the ruby standard library are used. -No external libraries. Only the native `json` and `net/http` standard libs are used. - ## Installation -1: Gemfile +Install with: -The SuperSaaS Ruby API Client is available from RubyGems and can be included in your project GemFile. Note, the supersaas-api-client may update major versions with breaking changes, so it's recommended to use a major version when expressing the gem dependency. e.g. + $ gem install supersaas-api-client - gem 'supersaas-api-client', '~> 1' +Alternatively, you can use `bundler` to install it by adding this line to you Gemfile. +The supersaas-api-client may update major versions with breaking changes, so it's recommended to use a major version when expressing the gem dependency. e.g. -2: System Gem + gem 'supersaas-api-client', '~> 2' -You can install the SuperSaaS Ruby API Client globally by using the gem command. Open a terminal and enter the following command: - - $ gem install supersaas-api-client - ## Configuration The `Client` can be used either (1) through the singleton helper method `instance`, e.g. Supersaas::Client.instance #=> <Supersaas::Client> @@ -65,63 +61,67 @@ Details of the data structures, parameters, and values can be found on the developer documentation site: https://www.supersaas.com/info/dev -#### List Schedules - -Get all account schedules: - - Supersaas::Client.instance.schedules.list #=> [<Supersaas::Schedule>, ...] - -#### List Resource - -Get all services/resources by `schedule_id`: - - Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...] - -_Note: does not work for capacity type schedules._ - #### Create User -Create a user with user attributes params: +Create a user with user attributes params `create(attributes, user_id = nil, webhook = nil, duplicate = nil)`. +If webhook=true is present it will trigger any webhooks connected to the account. +To avoid a ‘create’ action from being automatically interpreted as an ‘update’, you can add the parameter duplicate=raise, then error `422 Unprocessable Entity` will be raised. +If in your database your user has id 1234 then you can supply a foreign key in format 1234fk in `user_id` (optional) which you can use to identify user: +If validation fails for any field then error `422 Unprocessable Entity` will be raised and any additional information will be printed to your log. +Data fields that you can supply can be found [here.](https://www.supersaas.com/info/dev/user_api) - Supersaas::Client.instance.users.create({name: 'name@name.com', full_name: 'Example Name', email: 'example@example.com'}) #=> http://www.supersaas.com/api/users/12345.json + Supersaas::Client.instance.users.create({name: 'name@name.com', full_name: 'Example Name', email: 'example@example.com'}, '1234fk', true, 'raise') #=> http://www.supersaas.com/api/users/1234.json #### Update User -Update a user by `user_id` with user attributes params: +Update a user by `user_id` with user attributes params `update(user_id, attributes, webhook = nil, notfound = nil)`. +If webhook=true is present it will trigger any webhooks connected to the account. +To avoid automatically creating a new record, you can add the parameter notfound=error or notfound=ignore to return a 404 Not Found or 200 OK respectively. +If the `user_id` does not exist 404 error will be raised. +You only need to specify the attributes you wish to update: - Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}) #=> nil + Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}, true, "ignore") #=> nil #### Delete User -Delete a single user by `user_id`: +Delete a single user by `user_id`, and if the user does not exist 404 error will be raised. Supersaas::Client.instance.users.delete(12345) #=> nil #### Get User -Get a single user by `user_id`: +Get a single user by `user_id`, and if the user does not exist 404 error will be raised: Supersaas::Client.instance.users.get(12345) #=> <Supersaas::User> #### List Users -Get all users with optional `form` and `limit`/`offset` pagination params: +Get all users with optional `form` and `limit`/`offset` pagination params, `list(form = nil, limit = nil, offset = nil)`. +User can have a form attached, and setting `form=true` shows the data: Supersaas::Client.instance.users.list(false, 25, 0) #=> [<Supersaas::User>, ...] +#### List Fields of User object + +Get all the fields available to user object: + + Supersaas::Client.instance.users.field_list #=> [<Supersaas::FieldList>, ...] + #### Create Appointment/Booking -Create an appointment by `schedule_id` and `user_id` with appointment attributes and `form` and `webhook` params: +Create an appointment with `schedule_id`, and `user_id(optional)` (see API documentation on [create new](https://www.supersaas.com/info/dev/appointment_api#bookings_api)) appointment attributes and optional `form` and `webhook` params, +`create(schedule_id, user_id, attributes, form = nil, webhook = nil)`: Supersaas::Client.instance.appointments.create(12345, 67890, {full_name: 'Example Name', email: 'example@example.com', slot_id: 12345}, true, true) #=> http://www.supersaas.com/api/bookings/12345.json #### Update Appointment/Booking -Update an appointment by `schedule_id` and `appointment_id` with appointment attributes params: +Update an appointment by `schedule_id` and `appointment_id` with appointment attributes, see the above link, +`update(schedule_id, appointment_id, attributes, form = nil, webhook = nil)`: Supersaas::Client.instance.appointments.update(12345, 67890, {full_name: 'New Name'}) #=> nil #### Delete Appointment/Booking @@ -135,60 +135,117 @@ Supersaas::Client.instance.appointments.get(12345, 67890) #=> <Supersaas::Appointment> #### List Appointments/Bookings -List appointments by `schedule_id`, with `form` and `start_time` and `limit` view params: +List appointments by `schedule_id`, with `form` and `start_time` and `limit` view params, +`list(schedule_id, form = nil, start_time = nil, limit = nil)`: Supersaas::Client.instance.appointments.list(12345, 67890, true, true) #=> [<Supersaas::Appointment>, ...] #### Get Agenda -Get agenda (upcoming) appointments by `schedule_id` and `user_id`, with `from_time` view param: +Get agenda (upcoming) appointments by `schedule_id` and `user_id`, with `from_time` view param ([see](https://www.supersaas.com/info/dev/appointment_api#agenda), +`agenda(schedule_id, user_id, from_time = nil, slot = false)`: Supersaas::Client.instance.appointments.agenda(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Appointment>, ...] #### Get Agenda Slots -Get agenda (upcoming) slots by `schedule_id` and `user_id`, with `from_time` view param: +Get agenda (upcoming) slots by `schedule_id` and `user_id`, with `from_time` view param, +`agenda_slots(schedule_id, user_id, from_time = nil)`: Supersaas::Client.instance.appointments.agenda_slots(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Slot>, ...] -_Note: works only for capacity type schedules._ +_Note: only works for capacity type schedules._ #### Get Available Appointments/Bookings -Get available appointments by `schedule_id`, with `from` time and `length_minutes` and `resource` params: +Get available appointments by `schedule_id`, with `from` time and `length_minutes` and `resource` params ([see](https://www.supersaas.com/info/dev/appointment_api#availability_api), +`available(schedule_id, from_time, length_minutes = nil, resource = nil, full = nil, limit = nil)`: Supersaas::Client.instance.appointments.available(12345, '2018-01-31 00:00:00', 15, 'My Class') #=> [<Supersaas::Appointment>, ...] #### Get Recent Changes -Get recently changed appointments by `schedule_id`, with `from` time, `to` time and `slot` view param: +Get recently changed appointments by `schedule_id`, with `from` time, `to` time, `user` user, `slot` view params (see [docs](https://www.supersaas.com/info/dev/appointment_api#recent_changes)), +`changes(schedule_id, from_time = nil, to = nil, slot = false, user = nil, limit = nil, offset = nil)`: Supersaas::Client.instance.appointments.changes(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...] #### Get list of appointments -Get list of appointments by `schedule_id`, with `today`,`from` time, `to` time and `slot` view param: +Get list of appointments by `schedule_id`, with `today`,`from` time, `to` time and `slot` view params (see [docs](https://www.supersaas.com/info/dev/appointment_api#range)), +`range(schedule_id, today = false, from_time = nil, to = nil, slot = false, user = nil, resource_id = nil, service_id = nil, limit = nil, offset = nil)`: Supersaas::Client.instance.appointments.range(12345, false, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]/[<Supersaas::Slot>, ...] +#### List Forms -#### List Template Forms +Get all forms by template `superform_id`, with `from_time`, and `user` params ([see](https://www.supersaas.com/info/dev/form_api)): -Get all forms by template `superform_id`, with `from_time` param: - Supersaas::Client.instance.forms.list(12345, '2018-01-31 00:00:00') #=> [<Supersaas::Form>, ...] #### Get Form -Get a single form by `form_id`: +Get a single form by `form_id`, will raise 404 error if not found: Supersaas::Client.instance.forms.get(12345) #=> <Supersaas::Form> +#### Get a list of SuperForms + +Get a list of Form templates (SuperForms): + + Supersaas::Client.instance.forms.forms #=> [<Supersaas::SuperForm>, ...] + +#### List Promotions + +Get a list of promotional coupon codes with paging parameters `limit` and `offset` (see [docs](https://www.supersaas.com/info/dev/promotion_api)), +`list(template_form_id, from_time = nil, user = nil)`: + + Supersaas::Client.instance.promotions.list #=> [<Supersaas::Promotion>, ...] + +#### Get a single coupon code + +Retrieve information about a single coupon code use with `promotion_code`: + + Supersaas::Client.instance.promotions.promotion(12345) #=> <Supersaas::Promotion> + +#### Duplicate promotion code + +Duplicate a template promotion by giving (new) `id` and `template_code` in that order: + + Supersaas::Client.instance.promotions.duplicate_promotion_code(12345) #=> nil + +#### List Groups in an account + +List Groups in an account ([see](https://www.supersaas.com/info/dev/information_api)): + + Supersaas::Client.instance.groups.list #=> [<Supersaas::Group>, ...] + +#### List Schedules + +Get all account schedules: + + Supersaas::Client.instance.schedules.list #=> [<Supersaas::Schedule>, ...] + +#### List Services / Resources + +Get all services/resources by `schedule_id`: + + Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...] + +_Note: does not work for capacity type schedules._ + +#### List Fields of a Schedule + +Get all the available fields of a schedule by `schedule_id`: + + Supersaas::Client.instance.schedules.field_list(12345) #=> [<Supersaas::FieldList>, ...] + + ## Examples The ./examples folder contains several executable Ruby scripts demonstrating how to use the API Client for common requests. The examples will require your account name, api key, and some of the examples a schedule id and/or user id and/or form id. These can be set as environment variables. e.g. @@ -224,22 +281,19 @@ Supersaas::Client.instance.users.get rescue Supersaas::Exception => e # Handle error end -Validation errors are assigned to the response model. e.g. +Some errors have more information and are printed to the log before raising the error e.g. appointment = Supersaas::Client.instance.appointments.create(12345, {bad_field_name: ''}) - appointment.errors #=> [{"status":"400","title":"Bad request: unknown attribute 'bad_field_name' for Booking."}] + "Error 400, Bad request: unknown attribute 'bad_field_name' for Booking." ## Additional Information + [SuperSaaS Registration](https://www.supersaas.com/accounts/new) + [Product Documentation](https://www.supersaas.com/info/support) + [Developer Documentation](https://www.supersaas.com/info/dev) -+ [Python API Client](https://github.com/SuperSaaS/supersaas-python-api-client) -+ [PHP API Client](https://github.com/SuperSaaS/supersaas-php-api-client) -+ [NodeJS API Client](https://github.com/SuperSaaS/supersaas-nodejs-api-client) Contact: [support@supersaas.com](mailto:support@supersaas.com) ## Releases