ivvy Events Software API

Transcription

1 ivvy Events Software API Version 0.3 1

2 Contents Contents Document Control Revision History Introduction Obtaining Keys Creating the request Method/URI Header Request Headers Standard Headers HOST (Required) Date (Required unless using IVVY Date header) Content MD5 (Required) Content Type Content Length Custom Headers IVVY Date (Optional) IVVY Device UUID (Required) X Api Authorization (Required) X Api Version (Required) Signing the request Query Parameters Filter and Pagination Parameters Standard filter options Interpreting the response Success Exceptions Headers X Api Results Total X Api Results Slice Start X Api Results Slice Per Page Dates Push Notifications Common Parameters Event Notifications API Login Creating/Obtaining a User key Creating a Session Key 2

3 Password Reset Top Level Calls API Information Server Time Barcode Push Notifications Register for Push Notifications Account Account List (introduced in 0.3) Contact Create Contact (introduced in 0.3) Contact List (introduced in 0.3) Contact Options Specific Contact (introduced in 0.3) Update a Contact s Details Event Event List Specific Event Registration List Specific Registration List of Attendees Specific Attendee Fetch the fields that may be updated on an attendee Update the details of an attendee Update the timestamp of when the attendee attended an event Attendee Session List Attendee Session Update the timestamp of when the attendee attended a session Session List Specific Session Attendees of a Session Rate a Session Get the Attendee s Rating For a Session List of Exhibitors Specific Exhibitor List of Speakers Specific Speaker List of Sponsors Specific Sponsor List of Sponsor Levels List of Event Information Sending lead information to attendees Invoice 3

4 List of Invoices Specific Invoice Invoice Options Venue List of Invoices (introduced in 0.3) Specific Invoice (introduced in 0.3) Appendix A: Algorithms/Code Calculating MD5 Bash (Linux Command Line) Objective C HMAC SHA1 Javascript Objective C PHP Unix Timestamp Bash URLEncoding Appendix B: Objective C API Library (beta) Datasource Delegate Ivvy_Api API Request Methods makeapicall:withkey:andsecret:andpostdata: makeapicall:withpostdata: API Calls fetchuserkeyforaccount:withusername:andpassword: fetchuserkeyforevent:withusername:andpassword: fetchsessionkey: fetchinformation: Document Control The purpose of this document is to document the processes, procedures, and policies in relation to information security. This document should be updated every 6 months in response to changing risks and technology advances. Access to this document is also provided through a public url, Document No. 0.3 Effective Date 03/10/13 4

5 Revision No. 2 Revision History Date Rev No Change Reference Section(s) 23/04/ API Released 27/05/ More features made available on the API 14/10/ Changed http headers to use instead of _ Changed authorization string to drop the character from the IVVY headers before signing Contact API added 17/10/ Clarified dates Added invoice api section Request Headers Signing the request Contact Dates Invoice 22/10/ Added ability to update contact information Contacts 30/10/ Added payment methods to the OPTIONS method on the invoice api 07/11/ Added more information to the invoice api call Ability to add contacts Invoice Options Invoice Contacts 11/11/ Added Account api call Account 12/03/ Added Venue api call Venue Introduction The ivvy system is built with flexibility in mind, and this API forms a large part of that promise. Developers that require access to ivvy s API should contact ivvy s CTO, James Greig [email protected] 5

6 Obtaining Keys Keys are defined as a pair of strings, the key and the secret. Each request must be signed using the secret key. There are 4 types of keys used within the ivvy API. Developer: Reserved Application: Used by applications to sign the initial request for obtaining a User key User: Assigned to the user application device combination. This key is used to sign the request to get Session keys Session: This key is used to sign all requests for getting information from the API Each application shipped that communicates with the ivvy API must be shipped with a predetermined Application Key. This key is provided by ivvy administrators. Each version of the application must use a different key. The Application key is used in the first call to the API, along with some user credentials (username, password, account, event, etc) and a unique identifier for the device that is being used. This will result in a User Key being provided in the response. This key may be stored on the device (securely) to allow use of the application without asking user credentials every time. It is at the developer s discretion how often to ask the user for credentials. I.e. cache the user key for up to 5 minutes after the app has been closed, or store the user key indefinitely and require a more simple passcode for the user to access the application. Before api calls can be made, the user key must be used to obtain a session key. This key may expire at any time, and a new one can be requested at any time. In the case that a request has been rejected due to a stale key (i.e. the session key is no longer valid), the user key must be used to obtain another session key before continuing. Creating the request Requests to the API are over the standard HTTP (HyperText Transfer Protocol). The protocol defines three parts to every request 1. the method/uri header 2. a number of request headers 3. optional body of the request Method/URI Header This is a line consisting of the method of the request, followed by the request URI, followed by the HTTP version. i.e. 6

7 POST/api/loginHTTP/1.0 This example is for a POST request, to the /api/login api, using HTTP version 1.0. Request Headers Request headers are defined by the header name, followed by a colon (:) followed by a space, followed by the value of the header. A number of headers are used with the ivvy API Standard Headers HOST (Required) This determines the host that is used for the request. This value is required and should be set to wired.ivvy.com. I.e. HOST:wired.ivvy.com Date (Required unless using IVVY Date header) The date header determines the date the request was made. The ivvy API uses this date, compared to the date of the server to determine if the request is within the time to live setting (currently requests over 5 minutes old are deemed invalid, this value may change in the future). Date: Thu,12Apr201207:17:06UTC Content MD5 (Required) This is the md5 sum of the body of the request. This header is used to verify the contents of the body of the request have not been altered during transport. Note that if there is no content in the body, the MD5 for the request must still be calculated. See Calculating MD5 for more details on how to calculate the value for this field. Content Type The content type of the request body. Content Length The length of the request body, in bytes. Custom Headers A number of custom headers can be used with the request to the API. IVVY Date (Optional) If your HTTP client does not allow the date header to be accessed or set, you can optionally use this header to use for the date string. Note if this header is used, the date part of the signed string will need to be empty. The format of the value of this header will be the Unix timestamp, 7

8 NOT the string format of the standard Date header. IVVY Device UUID (Required) This determines the unique identifier of the device that is making the request to the API. The value may be used in this header to indicate that the request is not to be tied to a specific device. X Api Authorization (Required) This is the same format at the standard HTTP Authorization header. For ivvy requests, the format is... X-Api-Authorization:IWSkey:signature where IWS is the authentication system used by ivvy, key is the key used to sign the request, and the signature is the HMAC SHA1 signature of the request. See Signing the request for details on how to sign a request. The ivvy API server will lookup the secret key associated with the key used in this header, then use the details in the request in association with the secret key, reconstruct the HMAC SHA1 hash. Only when the calculated hash, and the signature sent through this header match will the request be authenticated. X Api Version (Required) Specify the version of the API to use. Note that API version are not guaranteed to be backward compatible so it is required that the request always specifies the version you want to use. Currently supported version are: Signing the request Every request to the API must be signed with the appropriate API key. Signing the request is obtained by the following pseudo code: method:=get POST DELETE PUT LIST contentmd5:=md5(<bodyoftherequest>) date:=thedateheaderoftherequest(i.e.tue,03apr,201222:23:24utc) NOTE:ifusingtheIVVY-Dateheader,thisfieldwillbeempty requeststring:=theentirerequeststringusedintherequest apiversion:=theapiversiontouse ivvyheaders:=concatenatedstringofallheadersstartingwithivvy,removingallthecharacters,inalphabeticalorder stringtosign:={method}{contentmd5}{date}{requeststring}{apiversion}{ivvyheaders} For example, the following request... 8

9 POST/api/loginHTTP/1.0 Host:wired.ivvy.com Date:Tue,03Apr201222:23:24UTC Content-MD5:776a6a2bce cdedfafee Content-Type:application/x-www-form-urlencoded Content-Length:70 X-Api-Version:0.2 X-Api-Authorization:IWS 6a03ba6ac33b90a23cf b263a1:99532db5e142ce7c99f28704b0c616c280e929f3 IVVY-Device-UUID:db3b8ed9b2a8e7f44b2b57ee413f6f9a account=test.com&username=xxxxx&password=xxxxx&name=xxxxx will require the following string to be signed post776a6a2bce cdedfafeetue,03apr201222:23:24 utc/api/login0.2ivvydeviceuuid=db3b8ed9b2a8e7f44b2b57ee413f6f9a Note the entire string is set to lowercase before signing. Signing is achieved using the HMAC algorithm, using SHA1 encryption. See HMAC SHA1 for further details Query Parameters Some calls to the ivvy API allow parameters to be passed through to the API endpoint. These parameters take the form of standard key value pairs as defined in the HTTP standard. For example, some API calls will take the following two keys as standard parameters to control pagination of results. perpage start As an example, if you want to get the third page results of ten results per page, you could format the query like this?perpage=10&start=3 The query string is separated by the api call with a question mark, followed by the key value pairs in the form of <urlencoded key>=<urlencoded password>. Each key value pair is separated by the ampersand (&) character. Note that each key and password MUST be urlencoded. Filter and Pagination Parameters Introduced in 0.3, some API calls now provide the option of filtering the results returned, and providing pages of results. Pagination is provided by passing two parameters to the api calls that support it. 9

10 perpage. Provides the ability to set the number of results per page returned by the api call. start. Provides the start record for the page. Note this is not the page number, but the record number to start results at. For example if the results were being sent at 10 per page, the first page will have a start of 0, the second page will have a start of 10, etc. Filtering is provided by passing the filter parameter through. The filter parameter can be specified a number of times, to combine each filter condition to the entire result list. This is done with some special syntax. Specify the filter parameter with the word filter Enclose the filter key and condition with brackets. I.e. [ and ] For equality match, the condition can be left out, for all other conditions, separate the key and the condition with two underscore ( _ ) characters. Provide the filter value as a normal parameter value. As an example the following query string might be used find all the contacts with the first name of Ben with the status of Subscribed filter[firstname]=ben&filter[status]=subscribed This will be the same as creating a filter on the contacts to be (firstname = Ben AND status = Subscribed). Standard filter options Where the API call takes the standard filter array, certain options may be provided to ensure the correct results are returned. A operator may be provided after the key, with two underscores (_) separating the key and the operator, to determine the correct filter to apply. If no operator is provided it is interpreted as an equality operator. As an example here are a few examples?filter[firstname]=ben?filter[modifieddate LESSTHAN]= The complete list of filter options that are interpreted by the API follow. CONTAINS: Return the results that contain the value. NOTCONTAINS: Return the results that do not contain the value. BEGINS: Return the results that start with the value. ENDS: Return the results that end with the value. LESSTHAN: Return the results that are less than or equal to the value. GREATERTHAN: Return the results that are greater than or equal to the value. NOT: Return the results that are not equal to the value. EMPTY: Returns results that are empty If you want to search for Null values, you can use the special value ISNULL for the filter 10

11 value. Interpreting the response The response will be given back in XML. The top level tag will be <ivvy>, with the more specific details of the response below that. Each response will be specific to the particular API call used. See the API documentation for details. Success The success response simply returns the success tag, with a message provided for the reason of the success. Exceptions If an error occurred the <exception>tag will be given as the response. This will provide the error code, a brief message as well as a specific code. The specific code is a useful piece of information to be provided in any bug reports. Current exception codes and meanings are: 400: Bad Request 401: Unauthorized 403: Forbidden 404: Not Found 405: Method Not Allowed 406: Not Acceptable 429: Too Many Requests 460: Unknown 461: Failed Request 462: Session Expired 463: Key Revoked 500: Internal Server Error 501: Not Implemented Some exceptions will have an additional piece of information associated with the exception, which may be used in some instances. For example, when requesting a barcode, and that barcode is not found, the exception response is returned with the value of the requested barcode in the response. <ivvy> <exception> <code>404</code> <message>unknownbarcode</message> <specificcode>24076</specificcode> <barcode>hjkh</barcode> </exception> 11

12 </ivvy> Headers Some requests will present different response headers, depending on the call that was serviced. X Api Results Total This header provides the total results that would have been returned if no pagination was provided on the result set. X Api Results Slice Start If the results are paginated, then this header will provide the record the results start from. Note this is not the page number, but the record number to start the page. For example, if you had a record count of 100 records per page, then page three would show an X-Api-Results-Slice-Startof 300 X Api Results Slice Per Page If the results are paginated, this header will provide the maximum number of records provided per page of results. Dates Responses from the ivvy API may contain dates. In all cases (unless otherwise stated in this document) the dates are in Universal Coordinated Time (UTC). Care must be taken when using or displaying these dates to ensure they: a) maintain their UTC timezone for communication with the API, and; b) represented in the appropriate timezone for users utilizing the date. Dates may be represented as a string which must be parsed appropriately if it is to be used. Where possible any dates will be converted to the Unix Timestamp standard, which is a single integer representing the number of seconds that have passed since the 1 January Again, this is represented in the UTC timezone. Methods for converting this integer to a date object should be available in all modern programming languages. Push Notifications Push notifications are implemented for devices that support this feature (at the moment, ios and Android). For this feature to work, the application must fetch an identifier on the device (see the provider s API for details). The app must then inform the ivvy service that the device is wanting push notifications. This is done using the Register for Push Notification api call. The app must also provide the ivvy API with the device type and the specific notification to register for. To register for a notification, the API call must provide some key value pairs to identify the type of notification to be registered for. Each type of notification might also provide further key value pairs to further limit the messages that might be sent. 12

13 Common Parameters All calls must identify the device type that is registering for the push notification. Currently known values are: Apple IOS: Android: devicetype=ios devicetype=android Event Notifications Event notifications are messages specific to an event being hosted by the ivvy website. Each event is identified uniquely by a code. To register for push notifications for a specific event, provide the key value pairs specified in the Common Parameters section, as well as the following key value pairs... type=event code=<eventcode> API Login Logging into the API is supported with either account access, or delegate access. If the login is with an account username/password, then the user will have access to all events within the account. Alternatively, if a delegate logs in using the events code, the returned results will only be for the event that delegate has been logged in to. Creating/Obtaining a User key 1. Sign the request with your Application key 2. Send a POST request to the /api/login URL 3. Parameters to post must have at least: a. username = The username to use b. password = The user s password And either one of the following: c. account = The account the user is logging into d. event = The event the delegate is logging into 4. You will get back a key specific for this user/account/device or user/event/device combination. Along with the request might be some specific information about the particular user that may be useful for future calls. 13

14 Creating a Session Key 1. Sign the request with your User key 2. Send a POST request to /api/login/0/session 3. You will get back a unique session key to be used to make api calls If the User Key that created this session was created from account credentials, then the session may be referred to as an Account Session. Some API features may be restricted to the Account Session and these restrictions will be identified in this document where they occur. Also, if the User Key that created this session was created from the event contact credentials, then the session may be referred to as an Event Session with restrictions identified throughout this document. Password Reset There are times where the user has forgotten their password to access the ivvy system and requires a new password to be generated. For this purpose the API provides a password reset call, which will reset the users password, then the new password to the user. After the reset password API has returned the success response, the old password will no longer apply. Please note this call is only available for the Event logins. Before this call is made on the API, it is expected the application will prompt the user to make sure that resetting the password is really what they would like to do, and perhaps giving a warning that resetting their password will invalidate their existing password. 1. Sign the request with your Application key. 2. Send a POST request to /api/login/0/password-reset 3. Parameters to post must contain the following information a. event = the event code the user is trying to login to b. = the address of the user to reset the password for 4. Response will either be success if the password was reset, or an exception if the username/event combination was not found. The application should then request the user to check their for the new password. Top Level Calls API Information 1. Send a GET request to /api/info 2. Response will contain the version information for the API <ivvy> <info> <version>0.2</version> 14

15 </info> </ivvy> Server Time 1. Send a GET request to /api/time 2. Response will be the time at the server <ivvy> <time> <timestamp> </timestamp> <timezone>utc</timezone> <datetime>april3,201210:32:04pmutc</datetime> </time> </ivvy> Barcode 1. Send a GET request to /api/barcode/<barcode> 2. Response will contain a string of text representing that barcode, as well as a type field that can be used to determine the type of object that barcode represents. <ivvy> <barcodetext=" t7307"> <description>johndoe</description> <type>attendee</type> </barcode> </ivvy> 3. In the case of an unknown barcode, an exception is returned with the value of the barcode is also returned in the response. <ivvy> <exception> <code>404</code> <message>unknownbarcode</message> <specificcode>24076</specificcode> <barcode>hjkh</barcode> </exception> </ivvy> Push Notifications Register for Push Notifications 1. Send a POST request to /api/push/<pushdeviceid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should provide the key value pairs of the push notification to register this device id to listen to, plus any further parameters required by the type if necessary. These are outlined in the Push Notifications section. 4. Response will be an exception on error, or the success response Account 15

16 Account List (introduced in 0.3) 1. Send a GET request to /api/account 2. The result will be a list of accounts the user has access to Contact Create Contact (introduced in 0.3) 1. Send a POST request to /api/contact 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request will be the key value pairs required to create a new contact. These are outlined below in the Contact Options api call. Note all the required fields must be provided. 4. The result will be an exception on error, or the success response. If the save was successful, the response will also contain an identifierattribute, which contains the id of the created contact Contact List (introduced in 0.3) Must use a session created with an account user key to access this api call. 1. Send a GET request to /api/contact 2. The query string may provide pagination and filter parameters. 3. The result will be a summary listing of the contacts. Note a maximum paging limit is specified on this list. If you wish to fetch every contact, you will need to fetch the results of this call a number of times, incrementing the start parameter each time, until the count of contacts is less than the value of the X Api Results Slice Per Page header. Note also the count of contacts appearing in the returned results only refer to the number of results returned on this request, not the entire number of contacts in the system (you can get this information by looking at the X Api Results Total header). Contact Options To get the fields that may be used to update contacts, you can make a call on the API to get a representation of what each of the fields are. 1. Send an OPTIONS request to /api/contact(note sending the same request to /api/contact/<contactid>has the same effect) 2. The result will be a list of all the fields that may be updated on the contact. Fields may be required. These fields may not be set to an empty value. Note that trying to update a contact that does not have all the required fields set will throw an exception, and will not 16

17 be updated until all the required fields have a valid value. Some fields have Single or Multiple select options. In these cases the key of the options are the only valid settings that can be made on these fields. Each field will have a key associated with it. This is the key that will be required to be used when updating the contact. Specific Contact (introduced in 0.3) 1. Send a GET request to /api/contact/<contactid> 2. Response will be the details of the specific contact requested. Note the result may or may not contain a customfields element. This element provides a list of custom fields, along with their values, that belong to the contact. These are setup by the account administrator as additional information to collect on a contact. Each custom field will have a filterkey attribute to specify how to filter for that field. To filter the list based on a custom field, provide a filter for filter[customfields][<filterkey>]=<filtervalue>. Update a Contact s Details 1. Send a POST request to /api/contact/<contactid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should provide the key value pairs of the information that is required to be updated, all urlencoded. To get a list of valid keys and value information, use OPTIONS method. 4. Response will be an exception on error, or the success response If the field to update is a Single Select or Multiple Select, then the value of the field must be equal to the key in one of the options available from the result of the OPTIONS call. If the field to update is a Multiple Select, and multiple values are to be sent through to be updated, then a special array syntax must be used in the body. For example, there may be a field called interests with the possible list of options as sport, photography, stargazing, computers. If you were to update the interests in the API call to be photography and computers, the post data should contain...&interests[]=photography&interests[]=computers&.... If the field is a date field, then the value should be sent as a Unix timestamp, in UTC. Event Event List 1. Send a GET request to /api/event 2. Response will be a list of events accessible by the user. 17

18 <ivvy> <eventscount="10"> <eventid="1"> <code>rbr9qogmq</code> <title>royalexhibition</title> <start> :00:00</start> <end> :30:00</end> <numregistered>511</numregistered> <status>launched</status> </event> <eventid="65"> <code>w2p3t3n77</code> <title>mattsabstracttestevent</title> <start> :00:00</start> <end> :00:00</end> <numregistered>0</numregistered> <status>launched</status> </event> <eventid="1887"> <code>qbc1e9</code> <title>davidtest</title> <start> :00:00</start> <end> :00:00</end> <numregistered>0</numregistered> <status>draft</status> </event> </events> </ivvy> Specific Event 1. Send a GET request to /api/event/<eventid> 2. Response will be the details of the specified event Included in the details of the specific event are two fields useful for mobile application development for delegate applications. The fields apptitle and appbanner will be set if the event organiser has filled in those fields. The app title is a short description (recommended to be 8 characters) that may be used in headings for example, instead of the potentially lengthy event name. The app banner will be an image that may be used to brand the application with a custom image. It is recommended to also provide a default placeholder image in case the event organiser has not provided this image. Registration List 1. Send a GET request to /api/event/<eventid>/registration 2. Response will be the list of registrations for the event Note if the Event Session key is in use, the registration list will be limited to the current users list of registrations. 18

19 Specific Registration 1. Send a GET request to /api/event/<eventid>/registration/<registrationid> 2. Response will be the details of the registration List of Attendees 1. Send a GET request to /api/event/<eventid>/attendee 2. Response will be the list of attendees on an event Note if this request is from an Event Session, then the list will be limited to the attendees that have set their profile to be public. If this request is from an Event Session, then the xml tag for each attendee will include the text self= true for all attendees that match the current user for the session. These attendees may be used to fetch specific details. An Event Session trying to fetch the specific details for an attendee other than the ones identifying themselves as self will fail. Specific Attendee 1. Send a GET request to /api/event/<eventid>/attendee/<attendeeid> 2. Response will be the details of the specific attendee Fetch the fields that may be updated on an attendee 1. Send a GET request to /api/event/<eventid>/attendee/<attendeeid>/fields 2. Response will be the fields that may be updated on an attendee. If the field is restricted to a specific set of values, these will also be included in the response for the specific fields. Each field will have a... Key. This key is to be used when updating the details of an attendee. Property specifying if the field is required or not. Type. The types available for fields are: Small Text Large Text Single Select. Must have a value from a list of options provided by the system. (These options are provided in the result as a list of <option/>tags.) Multiple Select. Can have multiple values assigned to the field. Each value must be selected from a list of options provided by the system. (These options are provided in the result as a list of <optionkey= optionkey >optionvalue</option>tags.) Date Display Name. This is an end user friendly label to describe what the input is for. Default. This will have the data that is already set for the field. It may be used to pre populate any form fields that to be modified. If the field is a multiple select, there may be multiple instances of this field. 19

20 Description. This is some end user friendly help text that may optionally be displayed to the user to help them decide what to enter for the field. Update the details of an attendee 1. Send a POST request to /api/event/<eventid>/attendee/<attendeeid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should provide the key value pairs of the information that is required to be updated, all urlencoded. To get a list of valid keys and value information, use the attendee fields api call as specified above. 4. Response will be an exception on error, or the success response If the field to update is a Single Select or Multiple Select, then the value of the field must be equal to the key in one of the options available from the attendee fields api call. If the field to update is a Multiple Select, and multiple values are to be sent through to be updated, then a special array syntax must be used in the body. For example, there may be a field called interests with the possible list of options as sport, photography, stargazing, computers. If you were to update the interests in the API call to be photography and computers, the post data should contain...&interests[]=photography&interests[]=computers&.... If the field is a date field, then the value should be sent as a Unix timestamp, in UTC Update the timestamp of when the attendee attended an event This call is only available to Account Sessions. 1. Send a POST request to /api/event/<eventid>/attendee/<attendeeid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should be, for example, attendedtimestamp= , where the timestamp is the Unix timestamp, in UTC. 4. Response will be an exception on error, or the success response. Attendee Session List 1. Send a GET request to /api/event/<eventid>/attendee/<attendeeid>/session 2. Response will be the list of sessions the attendee has signed up for Attendee Session 1. Send a GET request to /api/event/<eventid>/attendee/<attendeeid>/session/<sessionid> 2. Response will be details of the session the attendee is attending Update the timestamp of when the attendee attended a session This call is only available to Account Sessions. 1. Send a POST request to /api/event/<eventid>/attendee/<attendeeid>/session/<sessionid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should be, for example, attendedtimestamp= , where the 20

21 timestamp is the Unix timestamp, in UTC. 4. Response will be an exception on error, or the success response. Session List 1. Send a GET request to /api/event/<eventid>/session 2. Response will be the list of sessions available on the event Each session may have a list of speakers who are speaking at the session. These are represented in this API call as a number of <speaker>[speakerid]</speaker>tags. To get the details of the individual speaker, use the specific speaker call. Specific Session 1. Send a GET request to /api/event/<eventid>/session/<sessionid> 2. Response will be the details of a session Attendees of a Session 1. Send a GET request to /api/event/<eventid>/session/<sessionid>/attendee 2. Response will be the list of attendees of a session 3. To get details of the attendee, use the specific attendee call Rate a Session Each attendee may rate the sessions that they have attended 1. Send a POST request to /api/event/<eventid>/session/<sessionid>/rating/<attendeeid> 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should provide the key value pairs of the information that is required to be updated, all urlencoded. The following information is required. a. stars: A star rating for the session, a number between 1 and 5 b. comments: Some free text provided by the attendee 4. Response will be an exception on error, or the success response Get the Attendee s Rating For a Session 1. Send a GET request to /api/event/<eventid>/session<sessionid>/rating/<attendeeid> 2. Response will be the star rating and comments previously provided by the attendee on the specific session. <ivvy> <attendeeratingattendeeid="7246"sessionid="3553"> <rating>5</rating> <comments>good</comments> </attendeerating> </ivvy> List of Exhibitors 1. Send a GET request to /api/event/<eventid>/exhibitor 21

22 2. Response will be a list of exhibitors for the event Specific Exhibitor 1. Send a GET request to /api/event/<eventid>/exhibitor/<exhibitorid> 2. Response will be the details of the exhibitor The response XML may include zero, one or more <booth> nodes which indicate the booth names that are assigned to the exhibitor. List of Speakers 1. Send a GET request to /api/event/<eventid>/speaker 2. Response will be a list of speakers for the event Specific Speaker 1. Send a GET request to /api/event/<eventid>/speaker/<speakerid> 2. Response will be the details of the speaker Each speaker may have a list of sessions they are speaking at. These are represented in this API call as a number of <session>[sessionid]</session>tags. To get the details of the individual session, use the specific session call. List of Sponsors 1. Send a GET request to /api/event/<eventid>/sponsor 2. Response will be a list of sponsors of the event Specific Sponsor 1. Send a GET request to /api/event/<eventid>/sponsor/<sponsorid> 2. Response will be the details of the sponsor NOTE: the sponsor response includes a level attribute. See the sponsor levels call to get the name of the level this identifier is associated with. List of Sponsor Levels 1. Send a GET request to /api/event/<eventid>/sponsorlevel 2. Response will be the list of sponsor levels for the event <ivvy> <sponsorlevelscount="5"> <sponsorlevelid="9"> <id>9</id> <name>principal</name> <order>1</order> </sponsorlevel> <sponsorlevelid="8"> 22

23 <id>8</id> <name>platinum</name> <order>2</order> </sponsorlevel> <sponsorlevelid="7"> <id>7</id> <name>gold</name> <order>3</order> </sponsorlevel> <sponsorlevelid="6"> <id>6</id> <name>silver</name> <order>4</order> </sponsorlevel> <sponsorlevelid="5"> <id>5</id> <name>bronze</name> <order>5</order> </sponsorlevel> </sponsorlevels> </ivvy> List of Event Information 1. Send a GET request to /api/event/<eventid>/information 2. Response will be a list of information for delegates of the event Sending lead information to attendees Before making this call, a code must be obtained by the attendee to approve any leads to be sent to the attendee. Also, only event delegates can make this API call. 1. Send a POST request to /api/event/<eventid>/leadtracker 2. Content type of the request should be application/x-www-form-urlencoded 3. Body of the request should provide the following key value pairs: a. code: A code provided by the attendee to approve the use of the leadtracker b. barcodes: An array of barcodes that were scanned by the user. This is an array of data, so sending this through the request will be in the form similar to...&barcode[]=barcode1&barcode[]=barcode2&.... Note the use of square brackets to indicate this is an array of data. c. notes: An array of notes, which identify the notes to be supplied with the barcode. Note this is an array of data, and the indexes of the array will be the barcode that was scanned. An example request containing two barcodes (123 and 456) and providing notes for the barcodes, might be in the form...&barcode[]=123&barcode[]=456&notes[123]=note+1&notes[456]=note+2&.... Note the array in this case is indexed by the barcode. Also, because notes tend to be long and contain characters that need escaping, it needs a special mention to urlencode the notes (as it is for all the other fields) before constructing the request. 4. Response will be an exception on error, or the success response. 23

24 A special note on the success response. After a success message, an will be sent out to the user with a list of the leads represented by the barcodes, containing contact information for that lead. If the system finds a barcode it does not recognise, the system will report this in two ways. The first is instead of sending the Success message, the system will report Success. 5 barcode errors. (to indicate the number of barcodes that failed to be recognised). Following the message will be a number of barcodewitherror tags, each indicating a specific barcode that caused a processing error. For all the barcodes that did not fail, an will be sent out to the client containing the details of the client. Invoice List of Invoices 1. Send a GET request to /api/invoice 2. Response will be a list of invoices for the account Where appropriate, the response for each invoice may contain the following fields which might not be on every response. paymentduetimestamp: If there is a payment due date on the invoice, this field will be present eventid: If the invoice was created in the context of an event, this field will provide the identifier of the event venueid: If the invoice was created in the context of a venue, this field will provide the identifier of the venue tocontactid: If this invoice is linked to a specific contact, this field will provide the identifier of the contact NOTE: The toaddress object in the response may contain any of the following fields. line1: Not provided if empty line2: Not provided if empty line3: Not provided if empty line4: Not provided if empty city statecode: Not provided if empty, see statename instead. Also, if provided, the statename will be the display name of the statecode. statename: Not provided if empty. Note some countries (NZ for instance) do not have states. If a statecode is provided, this will be the display name for that code, else it will be the string provided by the user. countrycode: See the countryname for the display name of this country countryname: Display name for the code specified in countrycode postalcode 24

25 Specific Invoice 1. Send a GET request to /api/invoice/<invoiceid> 2. Response will be the details of the invoice The specific invoice call adds the invoice items and payments to the invoices. Invoice Options The invoice and item response contains a field called reftype. These are constants in the ivvy system to match the invoice or item to a specific entity. To find out a description of what these constants refer to, you can make a call to the api to get the complete list. 1. Send an OPTIONS request to /api/invoice 2. Response will be an options object with three lists a. invoicereftypes contains the reftype identifier and description of reftypes found in the invoice response. b. invoicelinereftypes contains the reftype identifier and description of reftypes found in the items of the invoice response. c. paymentmethods contains the complete list of payment methods that might appear against a payment made on an invoice. Venue List of Invoices (introduced in 0.3) 1. Send a GET request to /api/venue 2. Response will be a list of venues for the account Specific Invoice (introduced in 0.3) 1. Send a GET request to /api/venue/<venueid> 2. Response will be the details of the venue 25

26 Appendix A: Algorithms/Code Calculating MD5 The body of the request must have an MD5 hash calculated to ensure the body has not been altered during transport. It is important this is calculated the same as the ivvy API server to ensure the signature is calculated correctly and the request is authorized. Bash (Linux Command Line) $echo-n stringtohash md5sum 2fcc83d76f9b2d8ef372271d807a Note that any white space either side of the string will also be hashed, creating a different hash $echo-n" stringtohash " md5sum 6b9202a3b05bd22803fe54767b30ee10 - It is important you strip off any whitespace before hashing the string. Note also it is possible to hash an empty string (in the case there is no body in the request)... $echo-n"" md5sum d41d8cd98f00b204e ecf8427e - Objective C MD5 funcationlity can be be included in IOS code by first adding the CommonCrypto library to your target, and including the following function in your appdelegate (or appropriate class) #import<commoncrypto/commondigest.h>... +(NSString*)md5:(NSString*)input { constchar*cinput=[inpututf8string]; unsignedchardigest[cc_md5_digest_length]; CC_MD5(cInput,strlen(cInput),digest); NSMutableString*output=[NSMutableStringstringWithCapacity:CC_MD5_DIGEST_LENGTH*2]; for(inti=0;i<cc_md5_digest_length;i++){ [outputappendformat:@"%02x",digest[i]]; } returnoutput; }... HMAC SHA1 26

27 Javascript Cryptographic functions are available from the CryptJS libaray at js/. var stringtosign = string to sign ; var secret = my secret key ; var signature = CryptoJS.HmacSHA1 Objective C HMAC SHA1 functionality can be be included in IOS code by first adding the CommonCrypto library to your target, and including the following function in your appdelegate (or appropriate class) #import<commoncrypto/commondigest.h>... +(NSString*)hmac_sha1:(NSString*)inputusingSecret:(NSString*)key { constchar*ckey=[keyutf8string]; constchar*cinput=[inpututf8string]; unsignedchardigest[cc_sha1_digest_length]; if(ckey==nil cinput==nil){ return@""; } NSMutableString*output=[NSMutableStringstringWithCapacity:CC_SHA1_DIGEST_LENGTH* 2]; CCHmac(kCCHmacAlgSHA1,cKey,strlen(cKey),cInput,strlen(cInput),digest); for(inti=0;i<cc_sha1_digest_length;i++){ [outputappendformat:@"%02x",digest[i]]; } returnoutput; }... PHP Generating the HMAC SHA1 in PHP can be done using the following code. <?php $stringtosign= stringtosign ; $keysecret= mysecretkey ; $signature=hash_hmac( sha1,$stringtosign,$keysecret); echo$signature;?> This will generate an encrypted hash of the string. In this case the string will be a993876ea a1c da7b310dfae 27

28 Unix Timestamp The unix timestamp is defined as the number of seconds passed since 1 January All timestamps for the ivvy API are in this format, in the timezone UTC. Following are a few examples of how to convert to/from a unix timestamp... Bash $NOW=`date` $echo$now MonApr2309:19:18EST2012 $date-u+%s-d $NOW $NOW=`date-u+%s` $echo$now $date-d@$now-u ThuOct1700:52:34UTC2013 $date-d@$now ThuOct1710:52:34EST2013 URLEncoding To help pass special or reserved characters through URL s to the application, they must first be urlencoded. Most platforms provide such a feature. Following is a limited list of reserved characters you can provide the encoding to. Note this is NOT a comprehensive list, but a limited set provided for example only. For a more comprehensive list, see Character Encoded <space> %20? %3F & %26 %22 % %25 / %2F = %3D + %2B 28

29 29

30 Appendix B: Objective C API Library (beta) An objective c beta static library may be requested that provides some API functionality to make it easier to make requests correctly to the ivvy API server. Not all calls are implemented, but all the request signing and connection code has been provided. The code follows standard apple delegate/datasource protocols to provide flexibility in the way your application can communicate with the library. Any suggestions or improvements to the API will be appreciated. Datasource The datasource provides information to the api. This information is used during the api calls, to fetch keys specific to the application/user/session. Definition of the datasource -(NSString*)ivvyAPIApplicationKey; -(NSString*)ivvyAPIApplicationSecret; -(NSString*)ivvyAPIUserKey; -(NSString*)ivvyAPIUserSecret; -(NSString*)ivvyAPIDeviceUUID; -(NSString*)ivvyAPIApplicationName; -(NSString*)ivvyAPISessionKey; All the calls should be self explanatory. The optional method gives the datasource the chance to fetch a key and retry in case the session key was not provided to the library. As a general rule the AppDelegate could be used as the datasource, although you may want to provide your own singleton to provide an application wide object. A reference implementation of the optional method might be as follows... -(void)ivvyapifetchsessionkeyandtryagain:(ivvyapi*)api { NSLog(@""); IvvyAPI*api2=[[IvvyAPIalloc]init]; api2.delegate=self; api2.datasource=self; api2.userobject=api; [api2fetchsessionkey]; } 30

31 When the session key is fetched, this might be a possible delegate method to implement (see the next section for information about the delegate methods)... -(void)ivvyapi:(ivvyapi*)apididgetresult:(ivvyapi_object*)result { NSLog(@""); IvvyAPI_Key*key=(IvvyAPI_Key*)result; self.sessionkey=key.key; self.sessionsecret=key.secret; //Yay,nowwecancallourcallback... if([api.userobjectiskindofclass:[ivvyapiclass]]){ [api.userobjecttryagain]; } } Delegate Delegate methods are designed to give your application either full control over the response data, or allow the library to provide specific objects based on the recieved -(void)ivvyapi:(ivvyapi*)apididerror:(nserror*)error; -(void)ivvyapididstartconnecting:(ivvyapi*)api; -(void)ivvyapi:(ivvyapi*)apididgetresult:(ivvyapi_object*)result; -(void)ivvyapi:(ivvyapi*)apididgetexception:(ivvyapi_exception*)result; -(IvvyAPI_Object*)ivvyAPI:(IvvyAPI*)apididGetUnknownTag:(NSXMLParser*)parser withelementname:(nsstring*)nameandattributes:(nsdictionary*)attributes; -(void)ivvyapi:(ivvyapi*)apiparseresponsedata:(nsdata*)data; ivvyapi:diderror: will be called if there was an error connecting to the wired.ivvy.com service. ivvyapididstartconnecting: will be called on connection, this will give your app a chance to display the network indicator if necessary. ivvyapididfinishconnecting: will be called after network traffic has ceased, giving your app a chance to hide the network indicator if necessary. Optional methods are in two groups. The first group will give you specific objects from the call (these are only implemented in a couple of calls at the moment), the second group allow you to take control over the response from the api call. ivvyapi:didgetresult: Will provide an object with the result of the call ivvyapi:didgetexception: Will provide an exception object if the result is an exception ivvyapi:didgetunknowntag:withelementname:andattributes: 31

32 ivvyapi:parseresponsedata: If implemented, will be called with the NSData of the response. It is then up to the delegate to parse the response. Note this method will not be called if the ivvyapi:parseresponsestring: is also implemented. ivvyapi:parseresponsestring: If implemented, will be called with the NSString of the response. It is then up to the delegate to parse the response. Ivvy_Api API Request Methods makeapicall:withkey:andsecret:andpostdata: Makes an api call, with the given key/secret combination. If the post data is not nil, then the request will be a POST request with the given body. makeapicall:withpostdata: Makes an api call with the session key/secret as provided by the datasource. Using this method also saves the details so the tryagain: method may be called if required. If the ivvyapi:didgeterror: method is implemented in the delegate, an error may be thrown with the type IVVYApiErrorNoSessionKey indicating that we do not yet have a session key. Before this error is thrown the datasource may get the message to ivvyapifetchsessionkeyandtryagain: in which case the datasource has the oportunity to fetch a new session key, and call the tryagain: method. Each time this method is called, a counter is incremented (trycount) which can be read to avoid retrying too many times. By default the trycount will not try again after 3 tries. API Calls A limited number of API calls are provided within the library. This will expand in the future. Calls that are not provided will require the delegate to implement the parse functions to parse the XML response and store/use the data accordingly. fetchuserkeyforaccount:withusername:andpassword: Makes an API call to /api/login with the account/username/password combination. This method will get the ivvyapiapplicationkey and ivvyapiapplicationsecret from the datasource. If the ivvyapi:didgetresult: method is implemented in the delegate, an IvvyAPI_Key object should get returned. fetchuserkeyforevent:withusername:andpassword: Makes an API call to /api/login with the event/username/password combination. This method will get the ivvyapiapplicationkey and ivvyapiapplicationsecret from the datasource. If the 32

33 ivvyapi:didgetresult: method is implemented in the delegate, an IvvyAPI_Key object should get returned. fetchsessionkey: Makes an API call to /api/login/0/session with the ivvyapiuserkey and ivvyapiusersecret from the datasource. If the ivvyapi:didgetresult: method is implemented in the delegate, an IvvyAPI_Key object should get returned. fetchinformation: Makes an API call to /api/info with the users session keys. If the ivvyapi:didgetresult: method is implemented in the delegate, an IvvyAPI_Info object should be returned. 33