Question

I hired a backend developer to develop a REST API for my iPhone app. I need to give him a list of all HTTP requests that the iPhone is going to make. Is there a software that helps with planning out a REST API or do I just write it out in a plain TXT file with params and examples?

Answer 1

it would be best explained if you can give the developer the information regarding each service with what you expect to be passed and what you expect to be returned,

for example, this is how a service can be explained to register a device, (this is based on apples passbook server).

If you follow the structure as below the developer would have no problems with giving you exactly what you need.

/**
 # Registration
 # register a device to receive push notifications for a pass
 #
 # POST /v1/devices/<deviceID>/registrations/<typeID>/<serial#>
 # Header: Authorization: ApplePass <authenticationToken>
 # JSON payload: { "pushToken" : <push token, which the server needs to send push notifications to this device> }
 #
 # Params definition
 # :device_id      - the device's identifier
 # :pass_type_id   - the bundle identifier for a class of passes
 # :serial_number  - the pass' serial number
 # :pushToken      - the value needed for the Notification service
 #
 # server action: if the authentication token is correct, associate the given push token and device identifier with this pass
 # server response:
 # --> if registration succeeded: 201
 # --> if this serial number was already registered for this device: 304
 # --> if not authorized: 401
 */