تصميم:دواسوا/API

The API should implement the following verbs:

lookup

( name: string, count: int, index: int ): listings-enumeration

Returns count number of listings having name as the name, starting with index. Each listing item is comprised of basic package information sans contact information processed properly.

This is a GET request via the URL /lookup?name=&count=&index=

get_item_info

( id: string(id) ): item-info

Returns details information on a specific listing item; comprised of the package information and the contact information.

This is a GET request via the URL /item/id

request_insertion

( package-info: package-info, contact-info: contact-info, accept-terms: boolean )

Initiates an insertion request. Where:

• package-info : package information record
• contact-info : contact information record
• accept-terms : a boolean flag indicating the acceptance of the terms of service.

This request is a POST request

instate_listing

( token: string(cryptographic token) )

Instates a listing via user action.

This is a GET request via the URL /instate-listing/cryptographic-token

request_removal

( id: string(id) )

Initiates a listing deletion request

This is a GET request via the URL /delete-request/cryptographic-token

remove_listing

( token: string(cryptographic token) )

Initiates the removal of a listing from the public listings into the archive. Listings removed via this procedure have a status flag removed-by-user.

get_user_listings

( email-address )

Initiates a listings retrieval procedure

data structures

Listing data record is comprised of the following two data structures:

package_info

name : string

the name of the medicine in Latin script

name_arabic : string

the name of the medicine in Arabic script, if available (optional)

expiry : date

the date of expiry of the medicine. The significance is in the precision of months, i.e YYYY/MM

package_state : string(fabrica | opened | partial)

The case of the packaging of the medicine.

governrate : string(predefined)

the governerate where the package is to be picked up

description : text

a brief description, and/or notes by the submitter

photo : blob

an optional photograph of the package

contact_info

email_address : string(email-address)

email address identifies a user who enlists an item. It is used to communicate with the user to confirm his listing, and to confirm the removal of a listing. It's a user's means to control his listings. It could be made invisible to viewers of a listing unless no phone number is given, in which case it is the only means to contact the user by those interested in a listing.

name : string

A friendly name to greet the user by those contacting regarding a listing.

phone_number : string(phone-number)

An optional method to contact a user by those interested in a listing. If entered then it is visible.

email_address_visible : boolean

Determines whether the email address is visible. Ignored if no valid phone number is entered.