VATSIM PTD Documentation

Table of contents

• How to issue a certification
• How to add additional instructors
• API
  • Read-only public API
    • ATOs
    • Instructors
    • Certifications
    • Caching
  • Authenitcated certifications API
• Instructor accounts
• User Permissions
  • Superadmin
  • Admin
  • CFI
  • Instructor

How to issue a certification

• You must be an authorized ATO instructor or CFI with an account to the application
• You should have received a secure password by email when your acocunt was approved by VATSIM PTD staff
• With your email and password, use the Login link in the navigation menu on top to login into the app backend
• Select Pilot Certifications from the navigation menu on the left
• Click on the "Add New" tab
• In the trainee field find/type the vatsim member you want to issue a certification to. This field acts as a live serach field, you can type the person's name or Vatsim CID.
• In the rating field pick the rating you want to issue
• Click "Save". That's it. Screenshot below:

How to add additional instructors

• If you're an authorized ATO CFI you can add/suggest additional instructors for your ATO
• These people will be able to access the ptd app backend and issue certifications on behalf of your ATO
• To do that, go to the backend > Instructors > "Add new" tab
• Fill in the name, CID and email of the person you want to add as a new instructor. You won't have the option to specify an ATO: they will be assigned to your ATO
• The newly created Instructor record will be reviewed by VATSIM PTD staff, and when their account gets approved they will receive an email notification with their login password.
• Screenshot below:

API

Read-only public API

Public endpoints are available for pulling ATOs, Instructors and Certifications data in JSON, XML or CSV formats

ATOs

Example:

http://ptd.vatsim.net/api/atos.json  #=> returns active ATOs listing in JSON format
http://ptd.vatsim.net/api/atos.xml   #=> returns active ATOs listing in XML format
http://ptd.vatsim.net/api/atos.csv   #=> returns active ATOs listing in CSV format
http://ptd.vatsim.net/atos           #=> returns active ATOs listing as HTML (part of the web frontend)

Instructors

Example:

http://ptd.vatsim.net/api/instructors.json  #=> returns instructors listing in JSON format
http://ptd.vatsim.net/api/instructors.xml   #=> returns instructors listing in XML format
http://ptd.vatsim.net/api/instructors.csv   #=> returns instructors listing in CSV format
http://ptd.vatsim.net/instructors           #=> returns instructors listing as HTML (part of the web frontend)

Certifications

Example:

http://ptd.vatsim.net/api/certifications.json  #=> returns certifications listing in JSON format
http://ptd.vatsim.net/api/certifications.xml   #=> returns certifications listing in XML format
http://ptd.vatsim.net/certifications           #=> returns certifications listing as HTML (part of the web frontend)

Caching

All read-only APIs are rebuilt on a 12 hours cache

Authenitcated certifications API

The PTD application provides an API for programmatically issuing pilot rating certifications. You can hook this to your own ATO application in order to authomate the process of issuing pilot ratings and to avoid the manual labour of using the backend web interface.

In order to create an pilot certification, you send an HTTP POST request to http://ptd.vatsim.net/certifications with the JSON details of the new certification and with your ATO API key (sent as a HEADER along with the request).

The following parameters need to be sent with the request:

• cid - the VATSIM id of the pilot trainee
• instructor - the VATSIM id of the instructor issuing the upgrade. Note, this instructor must exist as a user in the PTD application
• rating - a single digit, corresponding to the rating issued, i.e. 1 for "P1", 2 for "P2", etc.

The API key for your ATO will be provided to you by the PTD staff.

Example:

# The following request will create a P2 rating certification for VATSIM user with cid 1175035
# issued from instructor with the VATSIM cid of 1111111. The ATO issuing the certification will
# be identified and included based on the supplied API key.

curl -X POST -H "Content-Type: application/json" -d '{"cid": "1175035","instructor":"1111111", "rating":"2"}' http://ptd.vatsim.net/certifications -H 'Authorization: Token token="your-ato-api-key"'

Notes:

• The example is a command line CURL call in a UNIX-based OS. The exact syntax will vary depending on the http client implementation and the language you're using. Refer to your http client's documentation for full reference.
• The order of attributes in the JSON string is irrelevant, just remember to wrap both the attribute name and the attribute value in quotes, use colon between the name (label) and the value, and separate the pairs with commas
• Use a header specifying the MIME type of the data being sent: in our case application/json.
• The authentication token (API key) is sent along as a HEADER!
• If the call has been successful and the record is created, the endpoint will return the new record as JSON, including all attributes PLUS the newly created record ID.
• If the call has'nt been successfull a json response including the encountered errors will be returned
• No record will be created without an authentication token

Instructor accounts

• Passwords for instructor accounts are generated and sent to the instructor upon triggering the "Approved" checkmark. Newly created or CFI suggested accounts pending admin review are inactive and login is not possible before the approval
• Unchecking the "Approved" field will result in revoking that instructor's permissions, setting his role to "inactive" and resetting his password, so that further login will be impossible. This situation can be reversed by re-apporving the instructor account.
• Email notifications will be sent to the instructor both on approving and disabling their account
• CFIs can suggest instructors by creating a record for them on the backend. CFIs are limited to only sugesting instructors within their own ATOs. The suggested accounts will be reviewed and approved by PTD admins and thereafter login credentials will be automatically sent to the new instructor.

User Permissions

Superadmin

can :manage, :all
cannot :create, Trainee
cannot :destroy, [Trainee, Ato, User]

Admin

can :read, :all
can :history, :all
can :export, :all

can :manage, [ApiKey, Ato, User, Trainee, Certificate, Certification]
cannot :destroy, [Ato, User, Trainee, Certification]
cannot :create, Trainee
cannot :export, Trainee

CFI

can :read, :all
cannot :read, ApiKey

can :history, [Ato, Certificate, Certification]
can :create, Certification
can :edit, Certification, :ato => {id: user.ato.id}
can :create, User, :ato_id => user.ato_id

Instructor

can :read, :all
cannot :read, ApiKey

can :history, [Ato, Certificate, Certification]
can :create, Certification
can :edit, Certification, :ato => {id: user.ato.id}