Nuestra XMLRPC API

El XMLRPC es una tecnología que me encanta al programar.

Permite abstraer funciones cliente servidor de forma transparente para el programador. Por ejemplo en mi claso mi cliente hace la llamada XMLRPC usando Python pero el servidor está desarrollado en PHP.

Hemos publicado la API que llamamos protocolo OSDB (Open Subtitles Data Base):

La podéis encontrar más detallada en el wiki, pero aquí estan los métodos resumidos:

  • array ServerInfo( )
    This simple function returns basic server info, it could be used for ping or telling server info to client.
  • array LogIn( $username, $password, $language, $useragent )
    This will login user. This function should be called always when starting talking with server. It returns token, which must be used in later communication. If user has no account, blank username and password should be OK. As language – use ISO639 2 letter code and later communication will be done in this language if applicable (error codes and so on). Note: when username and password is blank, status is 200 OK, because we want allow anonymous users too.
  • string LogOut( $token ) This will logout user (ends session id). Good call this function is before ending (closing) clients program.
  • array SearchSubtitles( $token, array(array(‘sublanguageid’ => $sublanguageid, ‘moviehash’ => $moviehash, ‘moviebytesize’ => $moviesize ),array(…)))

    This function returns information about found subtitles. It is designed making multiple search at once. Note – result is always grupped by MovieHash, MovieByteSize, SubLanguageID, IDSubMovieFile, sorted by seencount descending, max results is 100. When nothing is found, ‘data’ is empty.

  • array CheckSubHash( $token, array($SubHash, $SubHash, …) )

    This method returns IDSubtitleFile, if Subtitle Hash exists in database. If not exists, it returns ‘0’.

  • array CheckMovieHash( $token, array($MovieHash, $MovieHash, …) )

    This method returns MovieImdbID, MovieName, MovieYear, if available for each $MovieHash.

  • TryUploadSubtitles

    array TryUploadSubtitles( $token, array(‘cd1’ => array(‘subhash’ => $subMD5hash, ‘subfilename’ => $subfilename, ‘moviehash’ => $moviehash, ‘moviebytesize’ => $moviesize, ‘movietimems’ => $movietimems, ‘movieframes’ => $movieframes, ‘moviefps’ => $moviefps, ‘moviefilename’ => $moviefilename), ‘cd2’ => array(…) ) )

    This function needs to be called before UploadSubtitles(), because it is possible subtitles already exists on server. It takes 2 parameters, second parameter is array of information for subtitles to be uploaded, minimum cd1 is required. Mandatory fields are: subhash (md5 of subtitles), subfilename, moviehash, moviebytesize, moviefilename. It returns “alreadyindb” when subtitles already exists in database. When they do not exists, SearchSubtitles() is called, and API is looking for existing subtitles based on MovieHash/MovieSize. If some results are found, information is returned in “data” key as SearchSubtitles() return structure. This is good for uploading – user should have imdbid field already filled.

  • array UploadSubtitles( $token,array( ‘baseinfo’ => array ( ‘idmovieimdb’ => $idmovieimdb, ‘moviereleasename’ => $scene_releasename, ‘movieaka’ => $aka_in_subtitle_language, ‘sublanguageid’ => $sublanguageid, ‘subauthorcomment’ => $author_comment ), ‘cd1’ => array( ‘subhash’ => $md5subhash, ‘subfilename’ => $subfilename, ‘moviehash’ => $moviehash, ‘moviebytesize’ => $moviebytesize, ‘movietimems’ => $movietimems, ‘moviefps’ => $moviefps, ‘movieframes’ => $movieframes, ‘moviefilename’ => $moviefilename, ‘subcontent’ => $subtitlecontent ), ‘cd2’ => array (…) ) )

    This function have to be called after TryUploadSubtitles(). Many information are same, important part is subcontent. It should be gzip-ed (without header) and must be base64 encoded.

  • array SearchToMail( $token, array( $sublanguageid, $sublanguageid, …), array( array( ‘moviehash’ => $moviehash, ‘moviesize’ => $moviesize), array( ‘moviehash’ => $moviehash, ‘moviesize’ => $moviesize), …) )
    This is possible only for logged-in users. Scenario: user have directory with movies, for which he cannot find subtitles. With this function he subscribe to possible results, when someone else will upload matching subtitles. Once a day (or week…based on users profile) will system send subtitle link by mail to user. Note for developers: if it is possible, send moviehashes and moviesizes only for first CD in set (for example movie on two CDs), because users will receive duplicated mails (one for first cd and one for second cd)
  • array DownloadSubtitles( $token, array($IDSubtitleFile, $IDSubtitleFile,…) )

    Returns BASE64 encoded gzipped IDSubtitleFile(s). You need to BASE64 decode and ungzip ‘data’ to get its contents.

  • array ReportWrongMovieHash( $token, $IDSubMovieFile )

    This method is needed to report bad hash, e.g. subtitles are right for this movie file, but they are de-synchornized – for other version/release. With this method number of reports is counted in db, and after some number, hash will be automatically deleted from database.

  • array GetSubLanguages( $language = ‘en’ )

    Returns list of allowed subtitle languages, default is english language. Use ISO639-1 (2 characters code)

  • array GetAvailableTranslations( $token )

    Returns array of available translations for a program. In array you can find date of last created string and number of strings.

  • array GetTranslation( $token, $iso639, $format )

    Returns base64 encoded strings for language ($iso639) in some $format (mo, po, txt, xml). Use ISO639-1 (2 characters code)

  • array Autoupdate ( $program_name )

    This function returns latest version with info for $program_name

  • array NoOperation( $token )

    This function should be called each 15 minutes after last request to xmlrpc. It is used for not expiring current session. It also returns if current $token is registered.

Status codes

Successful 2xx

200 OK
206 Partial content; message

Errors 4xx

401 Unauthorized
402 Subtitles has invalid format
403 SubHashes (content and sent subhash) are not same!
404 Subtitles has invalid language!
405 Not all mandatory parameters was specified
406 No session
407 Download limit reached
408 Invalid parameters
409 Method not found
410 Other or unknown error
Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: