الفرق بين المراجعتين لصفحة «تصميم:دواسوا/API»

مراجعة 14:32، 1 يناير 2017

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 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.

@@ سطر 2: / سطر 2: @@
 The API should implement the following verbs:
-== <code>lookup ( <var>name</var>: string, <var>count</var>: int, <var>index</var>: int ): listings-enumeration</code> ==
+== <code>lookup</code> ==
+<code>( <var>name</var>: string, <var>count</var>: int, <var>index</var>: int ): listings-enumeration</code>
 Returns <var>count</var> number of listings having <var>name</var> as the name, starting with <var>index</var>. Each listing item is comprised of basic [[#package-info|package information]] sans [[#contact-info|contact information]] processed properly.
@@ سطر 8: / سطر 10: @@
-== <code>get_item_info ( <var>id</var>: string(id) ): item-info</code> ==
+== <code>get_item_info</code> ==
+<code>( <var>id</var>: string(id) ): item-info</code>
 Returns details information on a specific listing item; comprised of the [[#package-info|package information]] and the [[#contact-info|contact information]].
@@ سطر 15: / سطر 18: @@
-== <code>request_insertion ( <var>package-info</var>: [[#package-info|package-info]], <var>contact-info:</var> [[#contact-info|contact-info]], <var>accept-terms</var>: boolean )</code> ==
+== <code>request_insertion</code> ==
+<code>( <var>package-info</var>: [[#package-info|package-info]], <var>contact-info:</var> [[#contact-info|contact-info]], <var>accept-terms</var>: boolean )</code>
 Initiates an [[../workflow#insertion request|insertion request]]. Where:
 * [[#package-info|package-info]] : package information record
@@ سطر 23: / سطر 28: @@
-== <code>instate_listing ( <var>token</var>: string([[/cryptographic-token|cryptographic token]]) )</code> ==
+== <code>instate_listing</code> ==
+<code>( <var>token</var>: string([[/cryptographic-token|cryptographic token]]) )</code>
 [[../workflow#Listing instatement|Instates a listing]] via user action.
@@ سطر 29: / سطر 36: @@
-== <code>request_removal ( <var>id</var>: string(id) )</code> ==
+== <code>request_removal</code> ==
+<code>( <var>id</var>: string(id) )</code>
 Initiates a [[../workflow#removal request|listing deletion request]]
@@ سطر 35: / سطر 44: @@
-== <code>remove_listing ( <var>token</var>: string([[/cryptographic token|cryptographic token]]) )</code> ==
+== <code>remove_listing</code> ==
+<code>( <var>token</var>: string([[/cryptographic token|cryptographic token]]) )</code>
 Initiates the [[../workflow#Listing removal|removal of a listing]] from the public listings into the [[../archive|archive]]. Listings removed via this procedure have a status flag <kbd>by-user</kbd>.
-== <code>get_user_listings ( <var>email-address</var> )</code> ==
+== <code>get_user_listings</code> ==
+<code>( <var>email-address</var> )</code>
 Initiates a [[../workflow#Listings retrieval|listings retrieval]] procedure