/src/proto/spinn3rApi.proto

/*

http://code.google.com/p/spinn3r-client/source/checkout
SSH into repo and run:

    svn up
    protoc --proto_path=src/proto --java_out=src/java src/proto/spinn3rApi.proto
    ant compile
    svn commit -m "new protobufs"
    
*/

package contentApi;

option java_package         = "com.spinn3r.api.protobuf";
option java_outer_classname = "ContentApi";

message Link {
  /** The URL of this link */
  optional string href      = 1;
  /** The URL represented in Spinn3r's canonical form */
  optional string resource  = 2;
  /** The mime type of the data returned by this link */
  optional string mime_type = 3;
  /** The relative query string for this link */
  optional string rel       = 4;
}

message Lang {
  /** The language code */
  optional string code        = 1;
  /** Value between 0.0 and 1.0 indicating the probability the 
  the language indicated is the language of the content */
  optional float  probability = 2;
}

message Content {
  /** Mime type of this content */
  required string mime_type = 1;
  /** Bytes of the content */
  optional bytes  data      = 2;
  /** Data encoding, usually used for a compression format */
  optional string encoding  = 3;
}

message Author {
  /** Author's name */
  optional string name  = 1;
  /** Author's email */
  optional string email = 2;
  /** Author's website */
  repeated Link   link  = 3;
}

/**
 * TODO: geographic information for this blog.  Note that this might need to be
 * tied to an author.
 */
message Source {
  /** Link to source */
  repeated Link   link                  = 1;
  /** The link that Spinn3r uses to identify this source */
  optional Link   canonical_link        = 2;
  /** Title of the source */
  optional string title                 = 3;
  /** Source hashcode */
  optional string hashcode              = 4;
  /** Source language */
  repeated Lang   lang                  = 5;
  /** The Content Management System used to manage this source */
  optional string generator             = 6;
  /** Description of source, provided by the source */
  optional string description           = 7;
  /** Internal */
  optional int32  resource_status       = 8;
  /** The last time spinn3r discovered a new post for this source*/
  optional string last_posted           = 9;
  /** The last time this source published a new post */
  optional string last_published        = 10;
  /** Date that Spinn3r first crawled this source */
  optional string date_found            = 11;
  /** The etag last returned by this source's home page */
  optional string etag                  = 12;
  /** The probability that this RSS entry is spam. 
  Valid values are values between 0.0 and 1.0.
  If there is no spam_probability calculated, this
  value is set to -1.0. */
  optional float  spam_probability      = 13;
  /** Deprecated */
  optional sint32 tier                  = 14;
  /** Number of other sources that link to this source */
  optional int32  indegree              = 15;
  /** Publisher category */
  optional string publisher_type        = 16;
  /** Is this publisher disabled? */
  optional bool   disabled              = 17;
  /** The vendor that registered this source */
  optional string registered_by_vendor  = 18;
}

/**
 * This message represents an RSS feed
 */
message Feed {
  /** The links to this feed */
  repeated Link   link             = 1;
  /** The link that Spinn3r uses to identify this feed */
  optional Link   canonical_link   = 2;
  /** Title of the feed */
  optional string title            = 3;
  /** Hashcode of the feed */
  optional string hashcode         = 4;
  /** Language for the feed */
  repeated Lang   lang             = 5;
  /** The Content Management System used to manage this feed */
  optional string generator        = 6;
  /** Description of the feed */
  optional string description      = 7;
  /** Internal */
  optional int32  resource_status  = 8;
  /** Last time Spinn3r discovered a new entry in this feed*/
  optional string last_posted      = 9;
  /** Last time this feed published a new item */
  optional string last_published   = 10;
  /** The date spinn3r first crawled the feed */
  optional string date_found       = 11;
  /** The etag last returned by this feed */
  optional string etag             = 12;
  /** The probability that this RSS entry is spam. 
  Valid values are values between 0.0 and 1.0.
  If there is no spam_probability calculated, this
  value is set to -1.0. */
  optional float  spam_probability = 13;
  /** Channel link from RSS feed */
  optional Link   channel_link     = 14;
}

/**
 * raw_published:
 * 
 * The raw and opaque string specified by the entry, often in the HTML, which
 * represents the time the user/site thinks this story was published.  Although
 * this MAY be parsable by algorithsm like ISO 8601 or RFC 822, it may not be
 * parsable and internalized into a date model.  One example is if the site
 * omits a timezone.  Another is if they only use the day (Jan 1, 1970) and not
 * a time.
 */
message PermalinkEntry {
  /** The URLS of this Permalink Entry */
  repeated Link    link             = 1;
  /** The link that Spinn3r uses to identify this permalink entry*/
  optional Link    canonical_link   = 2;
  /** The link's title */
  optional string  title            = 3;
  /** The hashcode of this entry */
  optional string  hashcode         = 4;
  /** The language of this entry */
  repeated Lang    lang             = 5;
  /** The author of this entry */
  repeated Author  author           = 6;
  /** The category of this entry */
  repeated string  category         = 7;
  /** The probability that this RSS entry is spam. 
  Valid values are values between 0.0 and 1.0.
  If there is no spam_probability calculated, this
  value is set to -1.0.
   */
  optional float   spam_probability = 8;
  /** The date on which this entry was last published or updated */
  optional string  last_published   = 9;
  /** Date on which Spinn3r found this entry */
  optional string  date_found       = 10;
  /** An opaque identifier */
  optional int64   identifier       = 11;
  /** The content of the entry */
  optional Content content          = 12; 

  /** The content of the entry without the chrome */
  optional Content content_extract  = 13;
  /** The Content Management System used to manage this permalink entry */
  optional string  generator        = 14;
  /** Internal */
  optional string  raw_published    = 15;

}

/**
 * Deprecated
 */
message CrawlEntry {

  repeated Link    link                 = 1;
  optional Link    canonical_link       = 2;
  optional string  title                = 3;
  optional string  hashcode             = 4;
  repeated Lang    lang                 = 5;
  repeated Author  author               = 6;
  repeated string  category             = 7;
  optional float   spam_probability     = 8;
  optional string  last_published       = 9;
  optional string  date_found           = 10;
  optional int64   identifier           = 11;
  optional Content content              = 12;

  optional Content content_extract      = 13;
  optional string  generator            = 14;

  optional string  raw_published        = 15;

  optional string  domain_hashcode      = 16;
  optional string  subdomain_hashcode   = 17;

}

/**
 * This message represents an RSS feed item
 */
message FeedEntry {
  /** The URL to which the entry in the feed points */
  repeated Link    link             = 1;
  /** The link which Spinn3r uses to identify this FeedEntry */
  optional Link    canonical_link   = 2;
  /** The  tile of the entry */
  optional string  title            = 3;
  /** The hashcode */
  optional string  hashcode         = 4;
  /** The language of the feed entry */
  repeated Lang    lang             = 5;
  /** The author of the entry */
  repeated Author  author           = 6;
  /** The category of the entry */
  repeated string  category         = 7;
  /** The probability that this RSS entry is spam. 
  Valid values are values between 0.0 and 1.0.
  If there is no spam_probability calculated, this
  value is set to -1.0. */
  optional float   spam_probability = 8;
  /** The date on which the entry was late updated */
  optional string  last_published   = 9;
  /** The date on which Spinn3r first crawled this entry */
  optional string  date_found       = 10;
  /** An opaque identifier */
  optional int64   identifier       = 11;
  /** The content of the entry in the feed */
  optional Content content          = 12;  
}

/**
 * Entries for the comment api
 */
message CommentEntry {
    optional string permalink           = 1;
    optional string permalink_title     = 2;
    optional string permalink_hashcode  = 3;
    optional string raw_published       = 4;
    repeated Link link                  = 5;
    optional string date_found          = 6;
    optional Content content            = 7;
    optional string title               = 8;
    repeated Author author              = 9;
    optional string date_published      = 10;
    repeated string tag                 = 11;
    optional string lang                = 12;
}

/**
 * An entry is a representation of a piece of content
 * indexed by Spinn3r.
 */ 
message Entry {
  /** The web page from which this piece of content came */
  optional Source         source          = 1;
  /** The feed from which we discovered this piece of content.
   *  This field will not exist if we did not discover this 
   *  piece of content through a RSS feed. */
  optional Feed           feed            = 2;
  /** The feed item representing this piece of content. 
   *  This field will not exist if we did not discover this 
   *  piece of content through a RSS feed. */
  optional FeedEntry      feed_entry      = 3;
  /** The permalink representation of this content */
  optional PermalinkEntry permalink_entry = 4;
  /** This entry is only active when using the comment API */
  optional CommentEntry   comment_entry   = 5;
  /** Deprecated */
  optional CrawlEntry     crawl_entry     = 6;
  
  /** Deprecated */
  optional Content		  content 		  = 7;
  /** Deprecated */
  optional Content		  content_extract = 8;
}

/**
 * A response message is a collection of content. 
 */
message Response {
  /** The URL for this result set */
  optional string request_url          = 1;
  /** The URL for the previous result set */
  optional string previous_request_url = 2;
  /** The URL for the next result set */
  optional string next_request_url     = 3;
  /** The entries for the content. */
  repeated Entry  entry                = 4;
}


/**
 * 
 * Lang: 
 * 
 * The twitter/user specified language.  This might be incorrect but we like to
 * preserve all metadata.
 *
 * statuses_count:
 * 
 * total number of status updates from this user.
 * 
 */

/*

Tue Sep 01 2009 10:32 AM (burton@tailrank.com): NOTE: this is still in
development but I wanted to preserve this message signature as I believe we're
90% of the way there to supporting this extension.

message TwitterEntry {

  optional uint32 followers          = 1;
  optional uint32 friends            = 2;
  optional string location           = 3;
  optional string profile_image_url  = 4;
  optional string lang               = 5;
  optional uint32 statuses_count     = 6;
  optional bool   verified           = 7;
  
}
*/