ATN Application Release 2.0
API Reference
The API is a collection of calls for accessing AccessText database records over the web. Using the API, you can query and receive a list of records with associations from the database or add/edit single records within a table.
API Call Overview
- The API is invoked as a URL sent in a GET request.
- The response is in XML format.
- The API call parameters are accepted in any order.
- The username and apikey parameters are required and used to authenticate the user.
- You should always use secure HTTPS as HTTP is not supported.
Available Calls
Table | Call | Description |
---|---|---|
requests | do_query.xml | Return a list of requests with associated publisher, authorized_user, user, title and media data. |
requests | do_edit.xml | Update a single record in the requests table. The request record has a built-in id field which provides the unique key for that record within the table. |
requests | do_cancel.xml | Cancel a single record in the requests table. The request record has a built-in id field which provides the unique key for that record within the table. Only AuthorizedUsers can invoke this API call. |
requests | do_add.xml | Create a single record in the requests table. Only AuthorizedUsers can invoke this API call. Exchange requests cannot be added using the API. |
messages | do_query.xml | Return a list of messages with associated request, authorized_user, user and publisher data. |
messages | do_add.xml | Add a single record in the messages table. |
titles | do_query.xml | Returns title information. Useful when you need the title_id which is a required parameter for adding a request. |
titles | do_add.xml | Create a single record in the titles table. Only AuthorizedUsers can invoke this API call. Useful when you need the title_id which is a required parameter for adding a request. |
Requests
do_query.xml
Use do_query.xml to get all records from the requests table.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_query.xml?username=[your user name]&apikey=[your apikey]
where [your user name] and [your apikey] are the actual values for these parameters.
Optionally, you can pass the modified parameter with a date/time to limit the return to request records modified after a certain date/time.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_query.xml?username=[your user name]&apikey=[your apikey]&modified=[datetime]
where [datetime] is in the format YYYY-MM-DD HH:MM:SS or YYYYMMDDHHMMSS.
A sample request would look like:
https://accesstext.gatech.edu/atn20/requests/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&modified=20120701080000
All records from the requests table that the user johndoe is allowed to view and that have been modified after 8 AM on July 1, 2012 will be returned in XML format.
To return a specific request, you can pass the id parameter of the request you would like returned.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_query.xml?username=[your user name]&apikey=[your apikey]&id=[id]
where [id] is an integer.
A sample request would look like:
https://accesstext.gatech.edu/atn20/requests/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&id=12345
The request with unique ID 12345 the user johndoe is allowed to view will be returned in XML format.
Data from records related to the request record will also be returned. Data tables related to the request are the Authorized User making the request, the primary contact User for the Authorized User, the Title requested, the Publisher associated with the request, and the Media record related to the request if the request is an exchange request.
All fields for the Request, Authorized User, Title, and Media record will be returned. For the Publisher and User, only pertinent fields will be returned.
If multiple request records are returned, each record is contained within a <Record> tag. All records are contained with a <Requests> tag.
A sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <Request> <id>551</id> <authorized_user_id>11</authorized_user_id> <title_id>539149</title_id> <media_id>21</media_id> <publisher_id>41</publisher_id> <student_id>11</student_id> <course/> <instructor/> <term/> <request_type>Exchange</request_type> <status>Pending Approval</status> <format_requested/> <approval_method>Manual</approval_method> <date_approved/> <approval_assigned_to>131</approval_assigned_to> <approved_by>0</approved_by> <date_archive_requested/> <date_archive_received/> <projected_fulfillment_date/> <date_fulfilled/> <fulfillment_assigned_to/> <fulfilled_by>0</fulfilled_by> <fulfillment_method/> <format_delivered/> <tracking_number/> <download_expiration/> <date_received/> <cancel_request>0</cancel_request> <cancellation_reason/><date_cancelled/> <date_cancelled/> <cancelled_by>0</cancelled_by> <publisher_file_unavailable>0</publisher_file_unavailable> <disposition_date/> <disposition_code/> <disposition_reason/> <notes/> <download_available_days/> <number_downloads_allowed/> <download_information/> <download_link/> <created>2012-07-03 10:27:56</created> <modified>2012-07-03 10:27:56</modified> <created_by>DSS</created_by> <modified_by>DSS</modified_by> </Request> <Publisher> <id>41</id> <publisher_name>Pearson</publisher_name> </Publisher> <AuthorizedUser> <id>11</id> <authorized_user_name>CIDI</authorized_user_name> <type>Alternate Media Center</type> <institution_type>Other</institution_type> <last_verified/> <address1>123 Main</address1> <address2>Suite 1</address2> <city>Atlanta</city> <state>GA</state> <zip_code>30303</zip_code> <website/> <billing_name>John Doe</billing_name> <billing_title>Accountant</billing_title> <billing_addr1>456 State Street</billing_addr1> <billing_addr2>Suite 2</billing_addr2> <billing_city>NY</billing_city> <billing_state>NY</billing_state> <billing_zip>10101</billing_zip> <billing_phone>2025551111</billing_phone> <billing_fax/> <billing_email>john.doe@cidi.gatech.edu</billing_email> <notes>some notes.</notes> <created>2012-01-31 08:26:44</created> <modified>2012-04-19 11:48:50</modified> <created_by/> <modified_by>trunkle</modified_by> <User> <id>1</id> <authorized_user_id>11</authorized_user_id> <username>DSS</username> <full_name>Test DSS User</full_name> <email>dss@accesstext.org</email> <title>Disability Service Provider</title> <phone>(404) 555-1212</phone> </User> </AuthorizedUser> <Title> <id>539149</id> <reference>0201774712</reference> <title>A Course in Probability</title> <author>Weiss, Neil A.</author> <isbn10>0201774712</isbn10> <isbn13>9780201774719</isbn13> <edition>1</edition> <copyright>2006</copyright> <imprint>Addison Wesley</imprint> <publisher_id>41</publisher_id> <notes/> <file_name>test_file.docx</file_name> <publisher_file_unavailable>0</publisher_file_unavailable> <title_unavailable>0</title_unavailable> <manual_approval>0</manual_approval><source/> <stored_file_format>DOC</stored_file_format> <created>0000-00-00 00:00:00</created> <modified>2012-04-19 15:35:37</modified> <created_by/> <modified_by>trunkle</modified_by> </Title> <Media> <id>21</id> <title_id>539149</title_id> <publisher_id>41</publisher_id> <format>Embossed Braille</format> <file_name>test.doc</file_name> <file_source/> <tagged>0</tagged> <bookmarked>0</bookmarked> <headings>0</headings> <page_numbers>0</page_numbers> <daisy_format/> <ebraille_formatted>0</ebraille_formatted> <drm>0</drm> <notes/> <contributor>test</contributor> <contributor_email>test@test.com</contributor_email> <date_submitted/> <date_accepted>2012-03-10</date_accepted> <media_status>Accepted</media_status> <status_reason/> <alternate_text_images>0</alternate_text_images> <deny_exchange>0</deny_exchange> <exchange_file/><created>2012-03-13 16:14:34</created> <modified>2012-03-13 16:14:34</modified> <created_by/><modified_by/> </Media> </Record> </Requests> </atnapi>
do_edit.xml
Use do_edit.xml to update a single record in the requests table.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_edit.xml?username=[your user name]&apikey=[your apikey]&id=[id of record to update]&field1=value1&field2=value2 ...
where [your user name] and [your apikey] are the actual values for these parameters. The request record that will be updated is the request record with the id field equal to the value passed in for the id parameter. Fields and update values are passed as field=value parameters. Only the fields specified in the call are changed. Unspecified fields remain unchanged.
Only the following fields on the request record can be updated using the do_edit.xml call:
- date_approved
- date_archive_requested
- date_archive_received
- projected_fulfillment_date
- date_fulfilled
- fulfillment_method
- format_delivered
- tracking_number
- download_expiration
- publisher_file_unavailable
- disposition_date
- disposition_code
- disposition_reason
- download_available_days
- number_downloads_allowed
- download_information
- download_link
A sample request would look like:
https://accesstext.gatech.edu/atn20/requests/do_edit.xml?username=johndoe&apikey=x7z412mg6x8oht2r&id=551&date_approved=20120701
If the update is successful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>0</ErrorCode> <ErrorMessage>No Error</ErrorMessage> </Record> </Requests> </atnapi>
If the update is unsuccessful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to save record</ErrorMessage> </Record> </Requests> </atnapi>
do_cancel.xml
Use do_cancel.xml to cancel a single record in the requests table. Only requests in a pending status can be cancelled. Only AuthorizedUsers may invoke this call.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_cancel.xml?username=[your user name]&apikey=[your apikey]&id=[id of request to cancel]&date_cancelled=[YYYYMMDD]&cancellation_reason=[reason]
where [your user name], [your apikey], [date_cancelled], and [reason] are the actual values for these parameters. The request record that will be cancelled is the request record with the id field equal to the value passed in for the id parameter. Only the cancel_request, date_cancelled, cancellation_reason, cancelled_by, and status fields on the request will be updated using this call. The cancel_request field will automatically be set to true, the status field will be set to Cancelled, and the cancelled_by field will be set to the user invoking the API call. A sample request would look like:
https://accesstext.gatech.edu/atn20/requests/do_cancel.xml?username=johndoe&apikey=x7z412mg6x8oht2r&id=551&date_cancelled=20120701&cancellation_reason=Not+needed
If the cancel is successful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>0</ErrorCode> <ErrorMessage>No Error</ErrorMessage> </Record> </Requests> </atnapi>
If the cancel is unsuccessful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to cancel record</ErrorMessage> </Record> </Requests> </atnapi>
do_add.xml
Use do_add.xml to add a single record in the requests table. Only AuthorizedUsers can invoke this call. Exchange requests cannot be added using this API call.
This call is invoked as:
https://accesstext.gatech.edu/atn20/requests/do_add.xml?username=[your user name]&apikey=[your apikey]&field1=value1&field2=value2 ...
where [your user name] and [your apikey] are the actual values for these parameters. Fields and values are passed as field=value parameters.
The following fields on the request record are valid using the do_add.xml call:
- title_id (required) The title_id can be found using the do_query.xml call on the titles table for an ISBN.
- request_type (required) Either Publisher File, Permission to Scan Print Material, or Permission to Redistribute Alternative Text.
- format_requested (required when request_type is Publisher File)
- student_id (required)
- student_name (optional)
- student_disability (optional)
- course (optional)
- instructor (optional)
- term (optional)
- notes (optional)
- custom_text (optional)
- custom_numeric (optional)
- custom_date (optional)
- custom_checkbox (optional)
- custom_url (optional)
A sample request would look like:
https://accesstext.gatech.edu/atn20/requests/do_add.xml?username=johndoe&apikey=x7z412mg6x8oht2r&title_id=202187&student_id=abc&request_type=Publisher+File&format_requested=PDF
If the add is successful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>0</ErrorCode> <ErrorMessage>No Error. Request # created [where # is the actual ID number of the request]</ErrorMessage> </Record> </Requests> </atnapi>
If the add is unsuccessful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add record</ErrorMessage> </Record> </Requests> </atnapi>
Error Codes
If you invoke an API call without passing the username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Missing Credentials</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke an API call with incorrect username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Credentials</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_edit.xml or do_cancel.xml API calls without an id parameter, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Record ID</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_edit.xml or do_cancel.xml API call with an id parameter that your credentials are not allowed to update, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Permission Denied</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_edit.xml, do_cancel.xml, or do_add.xml API call with an invalid field name, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid field list</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_cancel.xml API call without passing the date_cancelled parameter, and error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Date Cancelled missing</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_cancel.xml API call without passing the cancellation_reason parameter, and error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Cancellation Reason missing</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_cancel.xml API call on a request that is already cancelled, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Request is already cancelled</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_cancel.xml API call on a request that is not in a pending status, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Only pending requests can be cancelled</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_cancel.xml or do_add.xml API call and your user role in not AuthorizedUser, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Only AuthorizedUsers can invoke this call</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and omit a required parameter, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>[Required Parameter: Either Title ID, Student ID, Request Type, or Format Requested] is missing</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and pass Exchange as the request type, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Exchange Request Type invalid in API</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and pass an invalid value for the title id or a title cannot be found for the value passed, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Title ID</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and the associated title record is marked as title unavailable, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add request as title is unavailable</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and the request type is Publisher File and the associated title record is marked as publisher file unavailable, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add publisher file request as publisher file is unavailable for title</ErrorMessage> </Record> </Requests> </atnapi>
If you invoke the do_add.xml API call and the request type is Publisher File and the associated title record is defined available formats and the value passed for format requested in not in the list of available formats for the title, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Requests> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add publisher file request as format requested is unavailable for title</ErrorMessage> </Record> </Requests> </atnapi>
Messages
do_query.xml
Use do_query.xml to get all records from the messages table.
This call is invoked as:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=[your user name]&apikey=[your apikey]
where [your user name] and [your apikey] are the actual values for these parameters.
As a second option, you can pass the modified parameter with a date/time to limit the return to message records modified after a certain date/time.
This call is invoked as:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=[your user name]&apikey=[your apikey]&modified=[datetime]
where [datetime] is in the format YYYY-MM-DD HH:MM:SS or YYYYMMDDHHMMSS.
A sample request would look like:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&modified=20120701080000
All records from the messages table that the user johndoe is allowed to view and that have been modified after 8 AM on July 1, 2012 will be returned in XML format.
As a third option, you can pass the rid parameter with a request id to limit the return to message records related to a particular request.
This call is invoked as:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=[your user name]&apikey=[your apikey]&rid=[requestid]
where [requestid] is the id number of the request.
A sample request would look like:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&rid=158798
All records from the messages table that the user johndoe is allowed to view and that are related to request 158798 will be returned in XML format.
For any of the above three calls, you can optionally add the from parameter to additionally limit the message records returned. Valid values from the from parameter are AuthorizedUser or Publisher.
A sample request would look like:
https://accesstext.gatech.edu/atn20/messages/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&modified=20120701080000&from=AuthorizedUser
All records from the messages table that the user johndoe is allowed to view and that have been modified after 8 AM on July 1, 2012 and that are from the AuthorizedUser will be returned in XML format.
Data from selected records related to the message record will also be returned. Data tables related to the message are the Request, the Authorized User making the request, the primary contact User for the Authorized User, and the Publisher associated with the request.
All fields for the Message record will be returned. For the Authorized User, Publisher and User, only pertinent fields will be returned. No data from the Request will be returned.
If multiple message records are returned, each record is contained within a <Record> tag. All records are contained with a <Messages> tag.
A sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <Message> <id>36460</id> <authorized_user_id>9</authorized_user_id> <publisher_id>4</publisher_id> <request_id>158798</request_id> <from>AuthorizedUser</from> <to>Publisher</to> <body>I want lunch</body> <created>2013-05-08 10:38:16</created> <modified>2013-05-08 10:38:16</modified> <created_by>etext@cidi.gatech.edu</created_by> <modified_by>etext@cidi.gatech.edu</modified_by> </Message> <AuthorizedUser> <id>9</id> <authorized_user_name>Alternative Media Access Center</authorized_user_name> <User> <id>245</id> <authorized_user_id>9</authorized_user_id> <username>etext@cidi.gatech.edu</username> <full_name>Todd Runkle</full_name> <email>trunkle@gatech.edu</email> <title/> <phone>(404) 894-8000</phone> </User> </AuthorizedUser> <Publisher> <id>4</id> <publisher_name>Cengage Learning</publisher_name> </Publisher> </Record> <Record> <Message> <id>36459</id> <authorized_user_id>9</authorized_user_id> <publisher_id>4</publisher_id> <request_id>158798</request_id> <from>AuthorizedUser</from> <to>Publisher</to> <body>green eggs and ham</body> <created>2013-05-08 10:38:08</created> <modified>2013-05-08 10:38:08</modified> <created_by>etext@cidi.gatech.edu</created_by> <modified_by>etext@cidi.gatech.edu</modified_by> </Message> <AuthorizedUser> <id>9</id> <authorized_user_name>Alternative Media Access Center</authorized_user_name> <User> <id>245</id> <authorized_user_id>9</authorized_user_id> <username>etext@cidi.gatech.edu</username> <full_name>Todd Runkle</full_name> <email>trunkle@gatech.edu</email> <title/> <phone>(404) 894-8000</phone> </User> </AuthorizedUser> <Publisher> <id>4</id> <publisher_name>Cengage Learning</publisher_name> </Publisher> </Record> </Messages> </atnapi>
do_add.xml
Use do_add.xml to add a single record in the messages table.
This call is invoked as:
https://accesstext.gatech.edu/atn20/messages/do_add.xml?username=[your user name]&apikey=[your apikey]&rid=[requestid]&body=[messagebody]
where [your user name] and [your apikey] are the actual values for these parameters. The message that will be added will be related to the request record with the id field equal to the value passed in for the rid parameter. The message text is contained within the message body parameters and should be URL encoded.
A sample request would look like:
https://accesstext.gatech.edu/atn20/messages/do_add.xml?username=johndoe&apikey=x7z412mg6x8oht2r&rid=158798&body=We+have+uploaded+the+file+and+the+download+should+now+work
If the add is successful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>0</ErrorCode> <ErrorMessage>No Error</ErrorMessage> </Record> </Messages> </atnapi>
If the add is unsuccessful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add message</ErrorMessage> </Record> </Messages> </atnapi>
Error Codes
If you invoke an API call without passing the username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Missing Credentials</ErrorMessage> </Record> </Messages> </atnapi>
If you invoke an API call with incorrect username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Credentials</ErrorMessage> </Record> </Messages> </atnapi>
If you invoke the do_add.xml API call without a rid parameter, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Missing Request ID</ErrorMessage> </Record> </Messages> </atnapi>
If you invoke the do_add.xml API call with a body parameter, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Messages> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Missing message body</ErrorMessage> </Record> </Messages> </atnapi>
Titles
do_query.xml
Use do_query.xml to get search for records in the titles table.
This call is invoked as:
https://accesstext.gatech.edu/atn20/titles/do_query.xml?username=[your user name]&apikey=[your apikey]
where [your user name] and [your apikey] are the actual values for these parameters.
You can search for titles by ISBN13 or by title.
If you use ISBN13, the search is an exact match.
A sample request would look like:
https://accesstext.gatech.edu/atn20/titles/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&isbn13=9780672321245
If you use title, the search is a contains match. In other words, all records where the title parameters is contained within the title field are returned. At most 100 records are returned. You can further limit the number of records returned by using the optional num parameter.
A sample request would look like:
https://accesstext.gatech.edu/atn20/titles/do_query.xml?username=johndoe&apikey=x7z412mg6x8oht2r&title=algebra&num=10
Ten records from the titles table where the title field contains the string algebra will be returned in XML format.
Data from the publisher related to the title record will also be returned. For the Publisher, only the publisher_id and publisher_name fields will be returned.
If multiple title records are returned, each record is contained within a <Record> tag. All records are contained with a <Titles> tag.
The value for the <id> field returned for a title is what is passed in for the title_id parameters when invoking the do_add.xml API call to add a request. Note that the id and isbn13 for a title are not the same value.
A sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <Title> <id>10</id> <reference>0672321246</reference> <author>Burton, Kevin</author> <isbn10>0672321246</isbn10> <isbn13>9780672321245</isbn13> <edition>1</edition> <copyright>2002</copyright> <publisher_id>1</publisher_id> <publisher_file_unavailable>0</publisher_file_unavailable> <title_unavailable>0</title_unavailable> <available_formats/> <notes>If you request a package, we will substitute the ISBN of the primary text and provide only that file (if available).</notes> <created/> <created_by/> <modified/> <modified_by/> </Title> <Publisher> <id>1</id> <publisher_name>Pearson Education</publisher_name> </Publisher> </Record> </Titles> </atnapi>
do_add.xml
Use do_add.xml to add a single record in the titles table. Only AuthorizedUsers can invoke this call.
This call is invoked as:
https://accesstext.gatech.edu/atn20/titles/do_add.xml?username=[your user name]&apikey=[your apikey]&field1=value1&field2=value2 ...
where [your user name] and [your apikey] are the actual values for these parameters. Fields and values are passed as field=value parameters.
The following fields on the request record are valid using the do_add.xml call:
- title (required)
- author (optional)
- edition (optional)
- copyright (optional)
- isbn13 (required)
- publisher_id (required)
- notes (optional)
A sample request would look like:
https://accesstext.gatech.edu/atn20/titles/do_add.xml?username=johndoe&apikey=x7z412mg6x8oht2r&title=Introduction+to+Algebra&author=Jones&edition=3©right=2013&isbn13=1234567890123&publisher_id=1
If the add is successful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>0</ErrorCode> <ErrorMessage>No Error. Title # created [where # is the actual ID number of the title record]</ErrorMessage> </Record> </Titles> </atnapi>
If the add is unsuccessful, a sample response would look like:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Unable to add record</ErrorMessage> </Record> </Titles> </atnapi>
Error Codes
If you invoke an API call without passing the username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Missing Credentials</ErrorMessage> </Record> </Titles> </atnapi>
If you invoke an API call with incorrect username and apikey credentials, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Credentials</ErrorMessage> </Record> </Titles> </atnapi>
If you invoke the do_query.xml API call and fail to pass either the isbn13 or title key, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid Search Key</ErrorMessage> </Record> </Titles> </atnapi>
If you invoke the do_add.xml API call and fail to pass the title, isbn13, or publisher_id key, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>[Key Field] missing</ErrorMessage> </Record> </Titles> </atnapi>
If you invoke the do_add.xml API call and try to add a title for an existing ISBN13, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>ISBN13 already exists</ErrorMessage> </Record> </Titles> </atnapi>
If you invoke the do_add.xml API call with an invalid field name, an error will be returned:
<?xml version="1.0" encoding="UTF-8"?> <atnapi> <Titles> <Record> <ErrorCode>1</ErrorCode> <ErrorMessage>Invalid field list</ErrorMessage> </Record> </Titles> </atnapi>