API

Myows API guide

V0.2 – 2010.03.09

Please post your questions and suggestions on our forum.
Scroll down to the bottom of the page or click here for tutorials and links relating to the Myows API
.

Brief Overview:

The Myows API is  a REST based API which is able to return output in a variety of formats. Because it Is REST based, the API accepts requests in the form GET PUT DELETE and POST. Each method accepts one of these types of requests, depending on it’s nature.

The Myows API makes use of the OAuth standard of authorization, allowing users to  authorize an application access to their data via a token based system. More information on OAuth can be found at http://oauth.net.

GET calls parameters are formatted as follows – the get parameters are put as part of the request, before the format specifier. For example, to add the sort_by=created parameter to the listOws call with output format JSON, it would become ows/listOWS/sort_by/created/format/json/

Methods

OWS:

Method Name: listOws

Description: List OWS filtering by a search string, solved cases only, active cases only, with the ability to sort based on a variety of fields listed below. Offset and limit are also options that may be specified.

Request Type: GET

Parameters:

·        search_string (string,optional)

·        case_filter (string, optional, ‘active’,’solved’)

·        sort_by (string, optional, options available are ‘created’, ‘title’, ‘type’,’client’,’category’,’size’)

·        offset (integer, optional, the offset to return the search results from)

·        limit (integer, optional, the number of results to return)

Return Values

·        error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·        ows (array of ow records)

id – Integer – The ID of this OW

user_id – Integer – The user id of this OWS owner (currently always the id of the authorised user)

title – String – The title of the OW

description – String – The description of the OW

category – String – The category the OW was placed under

client – String – The client the OW is for (if specified)

type – String – the mime type of the uploaded file

created – Date Time – The date and time the OW was created (format YYYY-mm-dd hh:mm:ss)

modified – Date Time – The date and time the OW information was last modified (format YYYY-mm-dd hh:mm:ss)

hash – String – The hash of the file that was taken upon registering the OW

original_hash – String – The original hash of the OW before any processing like resizing took place

resized – Boolean – Whether, if the OW is an image, it was resized or not.

size – Integer – The file size in kilobytes

ow_url – Integer – The url of the file object that this OW is associated with

display_url – String – The url of the file object that is used for display purposes (I.e. with the composited OW banner etc)

thumbnail_url – String – The url of the file object that is used for thumbnail display purposes (I.e. with the composited OW banner etc)

password – String – Password for the Ow

extension – String – File extension of the OW

active_cases – Integer – Number of active cases related to the OW

solved_cases – Integer – Number of solved cases related to the OW

licenses –  Integer – Number of licenses related to the OW

duplicates – Array

– number – Integer – The number of duplicates

– ids – Array – the ids of duplicate OWS


Output formats: JSON, XML

Method Name: owInfo

Request Type: GET

Parameters:

·        id (integer, required)

Return Values:

·       error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors) )

·        ow_info (array, contains all information pertaining to the OW)

·        attachments (array, contains all information about attachments to the OW)

Output formats: JSON, XML

ow_info – single row array(indexes)

id – Integer – The id of this OW

user_id – Integer – The user id of this OWS owner (currently always the id of the authorised user)

title – String – The title of the OW

description – String – The description of the OW

category – String – The category the OW was placed under

client – String – The client the OW is for (if specified)

type – String – the Mime type of the uploaded file

created – Date Time – The date and time the OW was created (format YYYY-mm-dd hh:mm:ss)

modified – Date Time – The date and time the OW information was last modified (format YYYY-mm-dd hh:mm:ss)

hash – String – The hash of the file that was taken upon registering the OW

original_hash – String – The original hash of the OW before any processing like resizing took place

resized – Boolean – Whether, if the OW is an image, it was resized or not.

size – Integer – The file size in kilobytes

ow_url – Integer – The url of the file object that this OW is associated with

display_url – String – The url of the file object that is used for display purposes (I.e. with the composited OW banner etc)

thumbnail_url – String – The url of the file object that is used for thumbnail display purposes (I.e. with the composited OW banner etc)

password – String – Password for the Ow

extension – String – File extension of the OW

active_cases – Integer – Number of active cases related to the OW

solved_cases – Integer – Number of solved cases related to the OW

licenses –  Integer – Number of licenses related to the OW

duplicates – Array

number – Integer – The number of duplicates

ids – Array – the ids of duplicate OWS

attachments – array – multirow or single indexes

id – Integer – Id of the Attachment

date – datetime – The date of the creation of this attachment. (format YYYY-mm-dd hh:mm:ss)

ow_id – Integer – The ID of the OW that this attachment is associated with.

attachment_url – string – The Url of the Attachment

Method Name: downloadOw

Description: Download a specific OW based on the Id of that OW

Request Type: GET

Parameters:

·        id (integer, required)

Return Values:

·      error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·      url – string – The URL file relating to the ow concerned (null if there is an error).

Output formats: The URL of the file relating to the OW concerned

Method Name: editOW

Description: Edit a specific OW based on the Id of that OW

Request Type: POST

Parameters:

·        id (integer, required)

·        ow_name (string, optional, the name of the ow)

·        category (string, optional, the category the ow is to be filed under)

·        client (string, optional, the client the ow is for)

·        description (string, optional, a description for this ow)

Return Values:

·        error_message (string, any pertinent error messages that need to be displayed, null if there are errors)

·        id (integer, the id of the ow just edited)

Output formats: JSON, XML

Method Name: sendOWCert

Description: Send an OW certificate to an individual based on the Id of that OW

Request Type: POST

Parameters:

·        id (integer, required)

·        email (string, required)

·        perpetrator_name (string, optional, the name of the perpetrator concerned)

·        to_name (string, optional, the name of the person sending the certificate)

Return Values:

·      error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

Output formats: JSON, XML

Method Name: changeOWPass

Description: Change the password of an OW on the Id of that OW

Request Type: POST

Parameters:

·        id (integer, required)

·        ow_pass (string, required, the password of the OW)

·        confirm_ow_pass (string, optional, password confirmation of the OW)

Return Values:

·        error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·        password (string, the password of the OW, only returned if the response is true).

Output formats: JSON, XML

Method Name: uploadOW

Description: Upload an OW

Request Type: POST

Parameters:

·        type (string, required, the type of upload occurring, can be file, batch, text)

·        ow_name (string, optional, the name of the ow. Required if flat text is being uploaded via an input field)

·        category (string, required, the category the ow is to be filed under)

·        client (string, required, the client the ow is for)

·        description (string, optional, a description for this ow)

·        UPLOAD_IDENTIFIER (string, required, client generated random 15 character unique alphanumeric string, used to identify the upload for uploadprogress calls)

·        flat_text (string, required if flat text is being uploaded via an input field)

·        register_file (The file data of the ow to be registered)

Return Values:


·        error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·        upload_status (boolean, the status of the upload, not the processing of the ow, only returned if the upload type is file).

·        ow_password (string, the password of the OW, only returned if the ow registered successfully, ie error_message is null), otherwise returned as null.

·        ow_id (integer, the id of the newly created ow, only returned if the registration of the ow was successful), otherwise returned as null.

Output formats: JSON, XML

Method Name: uploadOWProgress

Description: Check the progress of an upload

Request Type: POST

Parameters:

·        file_id (string, required, the 15 character unique alphanumeric string we supplied when we started our upload)

Return Values:

·        response (boolean, true or false)

·        array with the following items:

  • upload_id:
  • fieldname:
  • filename:
  • time_start:
  • time_last:
  • speed_average:
  • speed_last:
  • bytes_uploaded:
  • bytes_total:
  • files_uploaded:
  • est_sec:

{“upload_id”:”1HDULvJPFlhhNc9″,”fieldname”:”register_file”,”filename”:”VENT-Itchy_Feet-Addictech_Records.mp3″,”time_start”:”1264408149″,”time_last”:”1264408155″,”speed_average”:”11146″,

“speed_last”:”10238″,”bytes_uploaded”:”66877″,”bytes_total”:”11584829″,”files_uploaded”:”0″,”est_sec”:”1033″}

Output formats: JSON, XML

Method Name: addAttachment

Description: Add an attachment to a OW

Request Type: POST

Parameters:

·        ow_id (integer, required, the id of the ow we are attaching a file to)

·        UPLOAD_IDENTIFIER (string, required, 15 character unique alphanumeric string, used to identify the upload for uploadprogress calls)

·        register_file (The file form field of the attachment to be uploaded, can be submitted using curl)

Return Values:

·        error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·        upload_status (boolean, the status of the upload)

·        attachment_id (integer, the id of the newly created attachment, only returned if the registration of the ow was successful).

Output formats: JSON, XML

Method Name: downloadAttachment

Description: Download an OW attachment

Request Type: GET

Parameters:

·        attachment_id (integer, required, the id of the attachment we want to download)

Return Values:

·        error_message (string, any pertinent error messages that need to be displayed, null if there aren’t errors)

·        url – string – the time limited S3 url to the attachment.

Output formats: JSON, XML

Example URL or test string: http://myows.dev/api/ows/downloadAttachment/attachment_id/58/format/xml/

Authentication using Oauth:

The Myows API uses the OAuth standard for authentication and authorisation. Our implementation is compatible with the libraries that can be downloaded at http://code.google.com/p/oauth/ for various platforms.

All returns from the authentication portion of the system are in a standard url encoded string format.

Every application needs client credentials – a client key and secret. You can request these by going to https://myows.com/api_v1/oauth/register_consumer/.

Once you have client credentials, to obtain access to a specific user’s OWs the following steps must be taken (this process is documented thoroughly in the OAuth guide, and we have provided an example in PHP as well:

1. Obtain temporary credentials from Myows by making a signed request using your consumer key and secret to https://myows.com/api_v1/oauth/request_token.

2. Forward the user to the authorisation page, including the temporary credentials and a callback url. This is where the user will authorise the application to access their information. The url is https://myows.com/api_v1/oauth/authorize. If valid temporary credentials are not supplied, no request form will be displayed.

3. After the user has authorized the request, the callback url will be called with the temporary credentials. Now you can exchange the authorised temporary credentials for token credentials by making a signed call to https://myows.com/api_v1/oauth/access_token. Once you have the token credentials, they can be stored and used for access for this user, unless the user revokes application access.

Nettuts video tutorial: Create an App with the Myows API:

view the video tutorial on how to create a Myows App

Win an iPad and 1000$ by entering our 4 STEP API CHALLENGE:

4 step Api challenge