This guide lists a sample group of API methods which are recommended for use in order to create user interface layers either via web or desktop applications. All methods can be access in the Melative API (http://melative.com/api/).

 

User Methods

 

account/verify_credentials

 

URL:

http://melative.com/api/account/verify_credentials

 

Formats:

xml, json

 

HTTP Method:

GET

 

Purpose:

Used to verify a username-password combination and retrieve a user's profile record.

 

Description:

This method is similar in nature to that found in Twitter's API, more information can be found here.

 

Authentication:

Required. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

 

Example output:

<?xml version="1.0" encoding="utf-8"?>
 <user status="ok" ms="56.00309">
   <id>3</id>
   <profile_image_url>http://images.melative.com/user_x9c3bu1tprs1m1g2z3kr7x87h34k4qm3.jpg</profile_image_url>
   <name>RyanA</name>
   <sex>male</sex>
   <dob>1983-05-14</dob>
   <age>26</age>
   <location>Space County, Florida</location>
   <time_zone>EST</time_zone>
   <gmt_offset>GMT-5:00</gmt_offset>
   <utc_offset>-18000</utc_offset>
   <country>United States</country>
   <iso>en</iso>
   <language>English</language>
   <display_name>No Ryan, No</display_name>
   <description><![CDATA[....]]></description>
   <points>5999</points>
   <gravatar>81ea9344ad78cfae693c4115412a7edd</gravatar>
 </user>

 

 

users/show

 

URL:

http://melative.com/api/users/show

 

Format:

xml, json

 

HTTP Method:

GET

 

Purpose:

Used in order to retrieve a user's profile record. (For the non-authenticated user)

 

Description:

This method is similar in nature to that found in Twitter's API, more information can be found here.

 

Authentication:

Possibly required. Depending on the focus user's privacy settings, authentication may be required.

 

Parameters:

• Resolvable user
• user=name
• user_id=###

 

Example output:

<?xml version="1.0" encoding="utf-8"?>
  <user status="ok" ms="16.00099">
    <id>542</id>
    <profile_image_url>http://images.melative.com/user_1ltufro118s4sd52cuz4m1wepx1j3nns2.jpg</profile_image_url>
    <name>michaelrnz</name>
    <sex>male</sex>
    <age>21</age>
    <location>Christchurch, Canterbury</location>
    <time_zone>NST</time_zone>
    <gmt_offset>GMT+12:00</gmt_offset>
    <utc_offset>43200</utc_offset>
    <country>New Zealand</country>
    <iso>en</iso>
    <language>English</language>
    <display_name>michaelrnz</display_name>
    <description><![CDATA[]]></description>
    <points>543</points>
    <gravatar>8557109fd12abf2df3b53420e7f23bf3</gravatar>
  </user>

 

 

social/relations

 

URL:

 http://melative.com/api/social/relations

 

Format:

xml

 

HTTP Method:

GET

 

Purpose:

Retrieves a paginated list of relations (users) as related to the focus user.

 

Description:

The response for this method is a list (array) of user nodes with similar same structure to the users/show method (above). It is paginated (page,limit paramters). The output order is ascending by user-id.

 

Authentication:

Possibly required. Depending on the focus user's privacy settings, authentication may be required.

 

Parameters:

• Resolvable user
• user=name
• user_id=###
• Authentication (if no user resolved). 

   

 

Example output: (see users/show)

Each user node is contained within the <response> element (xml).

 

Roadmap:

This method will support json in the future.

 

fmp/follow

 

URL:

http://melative.com/api/fmp/follow

 

Format:

xml, json

 

HTTP Method:

POST

 

Converse method:

fmp/unfollow - used to unfollow the focus user.

 

Purpose:

Create a social relation between the authenticated user and a focus user (user=username or user_id=### params).

 

Description:

These FMP methods are part of the Nuclear core

 

Authentication:

Required. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

 

Parameters:

• Resolvable user
• user=name
• user_id=###

 

Example output:

Response containing status 'ok' or 'error' and a message element.

 

Roadmap:

This method will return a <user> node (see users/show) in the future.

 

 

Library Methods

 

library

 

URL:

http://melative.com/api/library

 

Format:

xml, json

 

HTTP Method:

GET

 

Purpose:

Retrieves a user's library based on a given context/entity type.

 

Description:

Outputs a list of <records> within a <library>. Records contain similar elements as the library/record method (see below), with the addition of system and entity data.

 

Authentication:

Possibly required. Depending on the focus user's privacy settings, authentication may be required.

 

Parameters:

• Resolvable user
• user=name
• user_id=###
• Resolvable entity-type (where type is a valid medium on Melative)
• context_type=type
• media=type

 

Example output:

<?xml version="1.0" encoding="utf-8"?>
  <response ms="252.01392">

   <library>
      <record>
        <added>2007-09-28 10:03:33</added>
        <updated>2007-09-28 10:03:33</updated>
        <state>complete</state>
        <completions>1</completions>
        <rating>700</rating>
        <status></status>
        <tags>historic, 明治時代, swordplay</tags>
        <segment></segment>
        <entity>
          <id>11</id>
          <type>anime</type>
          <image_url>http://images.melative.com/media_1xfa6c250zrw31op0ndq1a8u0231hk4euz.200.jpg</image_url>
          <aliase>Rurouni Kenshin</aliase>
          <meta></meta>
          <length></length>
          <duration></duration>
        </entity>
        <system>
          <users>21</users>
          <approval>46</approval>
          <rank>112</rank>
        </system>
      </record>
    </library>
  </response>

 

Roadmap:

This method should include more entity data in the future.

 

 

library/record

 

URL:

http://melative.com/api/library/record

 

Format:

xml (GET-only), json

 

HTTP Method:

GET, POST

 

Purpose:

Two-way skeleton (non-normal) method for creating, editing, and retrieving a bare-bones library record.

 

Description:

A library record is a single row within the database. It is returned as it exists or is modified with the addition of a response node for both GET and POST operations.

 

Required Parameters:

• Resolvable user (GET)
• user=name
• user_id=###
• Authentication (POST) 

   

• Resolvable Lime entity
• context_type=type and context_name=name
• type=name

 

Optional Parameters:

• state - A valid library-state
• (unknown, complete, current, wishlisted, started, paused, resumed, dropped, hold, planned, marathon, backlog, subscribed)
• added - Datetime added to library, format: YYYY-MM-DD HH:MM:SS (hour, minute, and second are optional)
• updated - Datetime of last update, same format as added
• completions - Number of times completed
• rating - A numeric rating to be parsed  and converted to a 1000-tier system. More information.
• segment - Text storage of the most recent segment updated. Format as type|name (Limit 128 characters, -1 unsets)
• status - Text storage (note-space) for a user's last status-update on the entity. (Limit ~500 characters, -1 unsets)
• tags - comma-delimited text storage for tags. (Limit ~500 characters, -1 unsets)

 

Authentication:

Required for POST. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

Possibly required for GET. Depending on the focus user's privacy settings, authentication may be required.

 

Example output:

<?xml version="1.0" encoding="utf-8"?>
   <record>
     <user>3</user>
     <lime_type>16</lime_type>
     <lime_id>34087</lime_id>
     <added>2010-03-18 23:23:56</added>
     <updated>2010-03-19 03:48:54</updated>
     <state>current</state>
     <completions>0</completions>
     <rating></rating>
     <recommendation></recommendation>
     <status>Fukken melt.</status>
     <segment>track|Oil and Water</segment>
     <tags></tags>
   </record>

 

Roadmap:

The segment element may be broken down (explode on '|') in order to provide type/name data rather than |-delimited.

 

Notes:

• Formally, 'segment' is/will be known as an attribute within the Lime framework.
• Updating state does modify the updated value if updated is not provided.
• Ratings are returned based on 1000-tier system. Please use custom ratings for resolving a user's custom system.

 

 

library/history

 

URL:

http://melative.com/api/library/history

 

Format:

xml, atom

 

HTTP Method:

GET

 

Purpose:

Provides a basic timeline of a user's library modifications and statuses generated via micro/udpate (see below).

 

Description:

Hybrid method, not entirely based on library modification but micro-update activity. Nodes are partial to ActionStatus format, and similar to Atom entries.

 

Parameters:

• Resolvable user (GET)
• user=name
• user_id=###

 

Example output:

<?xml version="1.0" encoding="utf-8"?>
  <history ms="44.00301">
    <user>
      <name>RyanA</name>
      <profile_image_url>http://images.melative.com/user_x9c3bu1tprs1m1g2z3kr7x87h34k4qm3.jpg</profile_image_url>
    </user>
    <entry>
      <id>25999</id>
      <timestamp>1270534209</timestamp>
      <created_at>Tue Apr 06 6:10:09 +0000 2010</created_at>
      <action>
        <verb>http://melative.com/api/actions/watched</verb>
        <entity>
          <id>tag:melative.com,2007:anime/339</id>
          <type>anime</type>
          <name>Aria the Animation</name>
          <attribute>
            <id>tag:melative.com,2007:anime/339:episode/10</id>
            <type>episode</type>
            <name>10</name>
          </attribute>
        </entity>
      </action>
      <text>I surely have a thing for winter episodes. Onsen is a bonus.</text>
    </entry>
  </history>

 

Roadmap:

• A full user node will be provided in the future.
• History by entity-type and entity will be available in the future (currently exist in other timelines).
• Source of the update may be provided in the future.
• There are no plans to provide an html content node.
• Prepending the action is still undecided. 

 

Notes:

• The atom format is a general feed, please use the xml method to render custom data representations.

 

 

library/scrobble

 

URL:

http://melative.com/api/library/scrobble

 

Format:

json

 

HTTP Method:

POST

 

Converse method:

library/unscrobble - unlogs a scrobbled segment (Lime attribute)

 

Purpose:

Provides segment logging capabilities for cataloging and progress.

 

Description:

Library scrobbling replaces the previous segment/update method although it functions similarly inside the application.

 

Required Parameters:

• Resolvable Lime entity
• context_type=type and context_name=name
• type=name
• Lime attribute
• attribute_type - Word (max 32 chars)
• may be assumed if not provided (type: tv, attribute type: episode)
• Examples: episode, track, chapter, volume, disc, issue, entry, movement, part, arc
• attribute_name - Identifier 
• Example attribute combinations:
• attribute_type=episode&attribute_name=5  => episode: 5
• attribute_type=track&attribute_name=Herons => track: Herons

 

Authentication:

Required. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

 

Example output:

Returns a Library record (see library/record) with a response element inside the <record>

 

Roadmap:

• Auto-creation of unidentified entities (currently supported by micro/update)
• XML output 

 

 

library/favorite

 

URL:

http://melative.com/api/library/favorite

 

Format:

json

 

HTTP Method:

POST

 

Converse method:

library/unfavorite

 

Purpose:

Add favorites to library (or in general for creators/characters)

 

Required Parameters:

• Resolvable Lime entity
• context_type=type and context_name=name
• type=name

 

Authentication:

Required. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

 

Example output:

Returns a Library record (see library/record) with a response element inside the <record>

 

Roadmap:

• Auto-creation of unidentified entities (currently supported by micro/update)
• XML output   

 

 

Other Methods

 

In addition to the above methods, Melative currently supports the majority of the status API methods as found on microblogging services like Twitter, Status.net (identi.ca), Wordpress, and Tumblr. The native microblogging method is below.

 

micro/update

 

URL:

http://melative.com/api/micro/update

 

Format:

xml, json

 

HTTP Method:

POST

 

Purpose:

Create a textual micro-update which may contain ActionStatus data.

 

Description:

Melative's micro/update is a unique feature which offers a command line-like interface for textual scrobbling, microblogging, and various other actions which may be used to catalog and edit in one's library.

 

Parameters:

• message (or status) - the text body of the update

 

Authentication:

Required. Valid authentication may be achieved with a valid Nuclear auth-token, session-based authentication, or http basic auth.

 

Example output:

Response containing 'ok' or 'error' and a message element.

 

Roadmap:

The method will return a <fp> node in the future, example format.