The odesk Reference Manual

Table of Contents

The odesk Reference Manual

This is the odesk Reference Manual, version 0.3.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:25:48 2020 GMT+0.

1 Introduction

=========================
What is cl-odesk?
=========================
This is cl-odesk, an implementation of the oDesk API in Common Lisp.

Spec URI: http://developers.odesk.com

=========================
Example Usage
=========================

If you already installed cl-odesk you can load it by::

 (require :odesk)

Before doing some API calls first you need to define connection. You will need PUBLIC_KEY, PRIVATE_KEY and TOKEN. The last one you can get only by authenticating yourself in your favourite web browser. Please read API Documentation at http://developers.odesk.com

You can create connection by instantiating API class::

 (defparameter *test-connection*
   (make-instance 'odesk:api-json
                  :public-key "PUBLIC"
                  :secret-key "SECRET"
                  :api-token "TOKEN"))

Here is macro that can ease your life a lot::

 (with-odesk (:connection con
              :public-key "PUBLIC"
              :secret-key "SECRET"
              :api-token "TOKEN")
   (print con))

And another macro that can help too::

 (connect-odesk (:public-key "PUBLIC"
                 :secret-key "SECRET"
                 :api-token "TOKEN"))

Now let's do request to get info about user.
If you went first way and created variable *test-connection*::

 (odesk:hr/get-user :connection *test-connection*)

If you go the second way and will use with-odesk macro. Here you have two options. The first one::

 (odesk:with-odesk
     (:connection my-con
      :public-key "PUBLIC"
      :secret-key "SECRET"
      :api-token "TOKEN")
   (odesk:hr/get-user :connection my-con))

The second::

 (odesk:with-odesk
     (:public-key "PUBLIC"
      :secret-key "SECRET"
      :api-token "TOKEN")
   (odesk:hr/get-user))

Third way is for those who want to create connection globally and then use it in the code with-out the need to use with-odesk macro::

 (odesk:connect-odesk (:public-key "PUBLIC"
                       :secret-key "SECRET"
                       :api-token "TOKEN"))
 (odesk:hr/get-user)

=========================
Supported API Calls
=========================

Authentication via Token
-----------------
* Get Token::

  auth/get-token (tested)

* Get frob::

  auth/get-frob (not tested)

* Check token::

  auth/check-token (tested)

* Revoke Session::

  auth/revoke-token (tested)

Authentication via OAuth
-----------------
no support at all.

URL Shortening
--------------

* Shorten URL::

  shorturl/get-shorten (tested)

* Expand URL::

  shorturl/get-expand (tested)

Financial Reporting
-----------------
* Generate Billing Reports for a Specific Provider::

  no support

* Generate Billing Reports for a Specific Provider's Team::

  no support

* Generate Billing Reports for a Specific Provider's Company::

  no support

* Generate Earning Reports for a Specific Provider::

  no support

* Generate Earning Reports for a Specific Provider's Team::

  no support

* Generate Earning Reports for a Specific Provider's Company::

  no support

* Generate Billing Reports for a Specific Buyer's Team::

  no support

* Generate Billing Reports for a Specific Buyer's Company::

  no support

* Generate Earning Reports for a Specific Buyer's Team::

  no support

* Generate Earning Reports for a Specific Buyer's Company::

  no support

* Generate Financial Reports for a Specific Account::

  no support

* Generate Financial Reports for an owned Account::

  no support

Custom Payments
-----------------

* Custom Payment::

  no support

Hiring. User Roles
-----------------

* User Roles::

  no support

* Referenced user::

  hr/get-user (tested)

Hiring. Jobs HR API
-----------------

* Returns all jobs that a user has manage_recruiting accesss to::

  no support

* Get Job by reference::

  no support

* Post a Job::

  no support

* Update Job::

  no support

* Cancel the Job::

  no support

Hirigin. Offers API
-----------------

* Lists all the offers on a specific job or within a specific team::

  no support

* Get Offer::

  no support

Hiring. Engagements API
-----------------

* Return engagement(s) based on the parameters supplied in the API call::

  no support

* Get Engagement::

  no support

Message Center
-----------------

* Retrieve a list of all active trays and a message count for each::

  mc/get-trays (tested)

* Retrieve tray contents::

  mc/list-tray (tested)

* List thread details based on thread id::

  no support

* Update threads based on user actions::

  no support

* Send a message to a user::

  no support

oConomy Reports API
-----------------

* Generate Monthly oDesk job market report::

  no support

* Generate Hours worked by location report::

  no support

* Generate oConomy weekly growth report::

  no support

* Generate Top countries by hours worked for last 30 days report::

  no support

* Generate Earnings by category report::

  no support

* Generate Monthly most requested skills report::

  no support

Organization
-----------------

* User Information::

  hr/get-myself (tested)

* Company Information::

  hr/get-companies (tested)

  hr/get-company (not tested)

  hr/get-company-teams (tested)

  hr/get-company-users (not tested)

* Team Information::

  hr/get-teams (tested)

  hr/get-team-users (not tested)

Provider Profile
-----------------

* Provider Information::

  profiles/get-provider (tested)

  profiles/get-provider-brief (tested)

Search Jobs
-----------------

* Searching Jobs::

  profiles/get-jobs (tested)

Search Providers
-----------------

* Searching Providers::

  profiles/get-providers (tested)

Snapshot
-----------------

* Get Snapshot::

  no support

* Update Snapshot Memo::

  no support

* Delete Snapshot::

  no support

oTasks
-----------------

* List all Tasks within a Company, Team or User::

  no support

* List all oTask records within a Company, Team or User::

  no support

* Return a specific task record within a company, team or user::

  no support

* Create an oTask record within a company, team or user::

  no support

* Update an oTask record within a company, team or user::

  no support

* Delete an oTask record within a company, team or user::

  no support

* Delete All oTask records within a company, team or user::

  no support

* Update a group of oTask records within a company, team or user::

  no support

Team
-----------------
* Get Team Rooms::

  team/get-teamrooms (tested)

* Get Team Room::

  team/get-teamroom (tested)

Work Diary
-----------------
* Get Work Diary::

  team/get-workdiary (tested)

Time Reports
-----------------
* Generate Time Reports for a Specific Team::

  timereports/get-team (tested)

* Generating Company Wide Reports::

  timereports/get-company (tested)

* Generating Agency Specific Reports::

  timereports/get-agency (tested)

* Generating Provider Specific Reports::

  timereports/get-provider (tested)

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 odesk

Author

Dmitriy Budashny <dmitriy.budashny@gmail.com>

License

BSD

Description

Common Lisp bindings for oDesk API

Version

0.3.1

Dependencies

• iterate
• md5
• drakma
• split-sequence
• cl-ppcre
• alexandria

Source

odesk.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 odesk/src

Parent

odesk (system)

Location

src/

Components

• packages.lisp (file)
• parameters.lisp (file)
• utils.lisp (file)
• odesk.lisp (file)
• requests.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 odesk.asd

Location

odesk.asd

Systems

odesk (system)

Packages

odesk-api-asd

Exported Definitions

*odesk-version-string* (special variable)

4.1.2 odesk/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

odesk

4.1.3 odesk/src/parameters.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/parameters.lisp

Exported Definitions

*connection* (special variable)

Internal Definitions

• *api-auth-url* (special variable)
• *api-base-url* (special variable)
• *gds-base-url* (special variable)
• *library-name* (special variable)
• *user-agent* (special variable)

4.1.4 odesk/src/utils.lisp

Dependency

parameters.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Internal Definitions

• format-url (function)
• get-page (function)

4.1.5 odesk/src/odesk.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/odesk.lisp

Exported Definitions

• api (class)
• auth-url (function)
• connect-odesk (macro)
• with-odesk (macro)

Internal Definitions

• api-token (method)
• (setf api-token) (method)
• api-url (method)
• (setf api-url) (method)
• api-version (method)
• (setf api-version) (method)
• build-auth-url (generic function)
• build-auth-url (method)
• data-format (method)
• (setf data-format) (method)
• def-gds (macro)
• def-req (macro)
• encode-url (generic function)
• encode-url (method)
• gds-url (method)
• (setf gds-url) (method)
• parse-page (generic function)
• parse-page (method)
• public-key (method)
• (setf public-key) (method)
• secret-key (method)
• (setf secret-key) (method)
• sign-url (generic function)
• sign-url (method)
• url-read (generic function)
• url-read (method)

4.1.6 odesk/src/requests.lisp

Dependency

odesk.lisp (file)

Parent

src (module)

Location

src/requests.lisp

Exported Definitions

• auth/check-token (function)
• auth/get-frob (function)
• auth/get-token (function)
• auth/revoke-token (function)
• hr/get-companies (function)
• hr/get-company (function)
• hr/get-company-teams (function)
• hr/get-company-users (function)
• hr/get-myself (function)
• hr/get-team-users (function)
• hr/get-teams (function)
• hr/get-user (function)
• mc/get-trays (function)
• mc/list-tray (function)
• profiles/get-jobs (function)
• profiles/get-provider (function)
• profiles/get-provider-brief (function)
• profiles/get-providers (function)
• shorturl/get-expand (function)
• shorturl/get-shorten (function)
• team/get-teamroom (function)
• team/get-teamrooms (function)
• team/get-workdiary (function)
• timereports/get-agency (function)
• timereports/get-company (function)
• timereports/get-provider (function)
• timereports/get-team (function)

5 Packages

Packages are listed by definition order.

5.1 odesk-api-asd

Source

odesk.asd

Use List

• asdf/interface
• common-lisp

Exported Definitions

*odesk-version-string* (special variable)

5.2 odesk

Source

packages.lisp (file)

Use List

• drakma
• split-sequence
• md5
• iterate
• common-lisp

Exported Definitions

• *connection* (special variable)
• api (class)
• auth-url (function)
• auth/check-token (function)
• auth/get-frob (function)
• auth/get-token (function)
• auth/revoke-token (function)
• connect-odesk (macro)
• hr/get-companies (function)
• hr/get-company (function)
• hr/get-company-teams (function)
• hr/get-company-users (function)
• hr/get-myself (function)
• hr/get-team-users (function)
• hr/get-teams (function)
• hr/get-user (function)
• mc/get-trays (function)
• mc/list-tray (function)
• profiles/get-jobs (function)
• profiles/get-provider (function)
• profiles/get-provider-brief (function)
• profiles/get-providers (function)
• shorturl/get-expand (function)
• shorturl/get-shorten (function)
• team/get-teamroom (function)
• team/get-teamrooms (function)
• team/get-workdiary (function)
• timereports/get-agency (function)
• timereports/get-company (function)
• timereports/get-provider (function)
• timereports/get-team (function)
• with-odesk (macro)

Internal Definitions

• *api-auth-url* (special variable)
• *api-base-url* (special variable)
• *gds-base-url* (special variable)
• *library-name* (special variable)
• *user-agent* (special variable)
• api-token (generic function)
• api-token (method)
• (setf api-token) (method)
• (setf api-token) (generic function)
• api-url (generic function)
• api-url (method)
• (setf api-url) (method)
• (setf api-url) (generic function)
• api-version (generic function)
• api-version (method)
• (setf api-version) (method)
• (setf api-version) (generic function)
• build-auth-url (generic function)
• build-auth-url (method)
• data-format (generic function)
• data-format (method)
• (setf data-format) (method)
• (setf data-format) (generic function)
• def-gds (macro)
• def-req (macro)
• encode-url (generic function)
• encode-url (method)
• format-url (function)
• gds-url (generic function)
• gds-url (method)
• (setf gds-url) (method)
• (setf gds-url) (generic function)
• get-page (function)
• parse-page (generic function)
• parse-page (method)
• public-key (generic function)
• public-key (method)
• (setf public-key) (method)
• (setf public-key) (generic function)
• secret-key (generic function)
• secret-key (method)
• (setf secret-key) (method)
• (setf secret-key) (generic function)
• sign-url (generic function)
• sign-url (method)
• url-read (generic function)
• url-read (method)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *connection*

Package

odesk

Source

parameters.lisp (file)

Special Variable: *odesk-version-string*

cl-odesk version number as a string.

Package

odesk-api-asd

Source

odesk.asd

6.1.2 Macros

Macro: connect-odesk (&key FORMAT PUBLIC-KEY SECRET-KEY API-TOKEN)

Package

odesk

Source

odesk.lisp (file)

Macro: with-odesk (&key CONNECTION FORMAT PUBLIC-KEY SECRET-KEY API-TOKEN) &body BODY

Package

odesk

Source

odesk.lisp (file)

6.1.3 Functions

Function: auth-url &key CONNECTION FROB

Return authentication url to be used in browser.

Package

odesk

Source

odesk.lisp (file)

Function: auth/check-token &key CONNECTION PARAMETERS

Return authenticated user associated with authorization token.

Package

odesk

Source

requests.lisp (file)

Function: auth/get-frob &key CONNECTION PARAMETERS

Get authentication frob.

Package

odesk

Source

requests.lisp (file)

Function: auth/get-token &key CONNECTION PARAMETERS

Get authentication token.

Package

odesk

Source

requests.lisp (file)

Function: auth/revoke-token &key CONNECTION PARAMETERS

Revoke given auth.

Package

odesk

Source

requests.lisp (file)

Function: hr/get-companies &key CONNECTION PARAMETERS

Return all the companies the current authorized user has access to on oDesk

Package

odesk

Source

requests.lisp (file)

Function: hr/get-company &key CONNECTION PARAMETERS COMPANY

Return details regarding a specific company

Package

odesk

Source

requests.lisp (file)

Function: hr/get-company-teams &key CONNECTION PARAMETERS COMPANY

Return a list of teams within the company being referenced

Package

odesk

Source

requests.lisp (file)

Function: hr/get-company-users &key CONNECTION PARAMETERS COMPANY

Return a list of all users within the referenced company

Package

odesk

Source

requests.lisp (file)

Function: hr/get-myself &key CONNECTION PARAMETERS

Return info about current authenticated user

Package

odesk

Source

requests.lisp (file)

Function: hr/get-team-users &key CONNECTION PARAMETERS TEAM

This will return user details for all users in the referenced team

Package

odesk

Source

requests.lisp (file)

Function: hr/get-teams &key CONNECTION PARAMETERS

This call returns all the teams that a user has acccess to

Package

odesk

Source

requests.lisp (file)

Function: hr/get-user &key CONNECTION PARAMETERS USER

Return info about some user

Package

odesk

Source

requests.lisp (file)

Function: mc/get-trays &key CONNECTION PARAMETERS

Retrieve a list of all active trays and a message count for each.

Package

odesk

Source

requests.lisp (file)

Function: mc/list-tray &key CONNECTION PARAMETERS USERNAME TRAY

Retrive tray contents.

Package

odesk

Source

requests.lisp (file)

Function: profiles/get-jobs &key CONNECTION PARAMETERS

Search for jobs.

Package

odesk

Source

requests.lisp (file)

Function: profiles/get-provider &key CONNECTION PARAMETERS PROVIDER

Return detailed profile information about provider

Package

odesk

Source

requests.lisp (file)

Function: profiles/get-provider-brief &key CONNECTION PARAMETERS PROVIDER

Return brief profile information about provider

Package

odesk

Source

requests.lisp (file)

Function: profiles/get-providers &key CONNECTION PARAMETERS

Search for workers.

Package

odesk

Source

requests.lisp (file)

Function: shorturl/get-expand &key CONNECTION PARAMETERS

Return expanded url.

Package

odesk

Source

requests.lisp (file)

Function: shorturl/get-shorten &key CONNECTION PARAMETERS

Return shortened url.

Package

odesk

Source

requests.lisp (file)

Function: team/get-teamroom &key CONNECTION PARAMETERS TEAM

Get all teamrooms accessible to the user.

Package

odesk

Source

requests.lisp (file)

Function: team/get-teamrooms &key CONNECTION PARAMETERS

Get all teamrooms accessible to the user.

Package

odesk

Source

requests.lisp (file)

Function: team/get-workdiary &key CONNECTION PARAMETERS COMPANY USERNAME DATE

Retrieve all snapshots from a single user account within a single day

Package

odesk

Source

requests.lisp (file)

Function: timereports/get-agency &key CONNECTION PARAMETERS COMPANY AGENCY

Generate time report for a specific agency

Package

odesk

Source

requests.lisp (file)

Function: timereports/get-company &key CONNECTION PARAMETERS COMPANY

Generate company wide time reports

Package

odesk

Source

requests.lisp (file)

Function: timereports/get-provider &key CONNECTION PARAMETERS PROVIDER

Generate time report for a specific provider

Package

odesk

Source

requests.lisp (file)

Function: timereports/get-team &key CONNECTION PARAMETERS COMPANY TEAM

Generate time report for a specific team

Package

odesk

Source

requests.lisp (file)

6.1.4 Classes

Class: api ()

Package

odesk

Source

odesk.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• parse-page (method)
• url-read (method)
• build-auth-url (method)
• encode-url (method)
• sign-url (method)
• gds-url (method)
• gds-url (method)
• api-url (method)
• api-url (method)
• api-version (method)
• api-version (method)
• api-token (method)
• api-token (method)
• secret-key (method)
• secret-key (method)
• public-key (method)
• public-key (method)
• data-format (method)
• data-format (method)

Direct slots

Slot: data-format

Data Format

Initargs

:data-format

Initform

"json"

Readers

data-format (generic function)

Writers

(setf data-format) (generic function)

Slot: public-key

Public key

Initargs

:public-key

Initform

(error "must supply public key.")

Readers

public-key (generic function)

Writers

(setf public-key) (generic function)

Slot: secret-key

Secret key

Initargs

:secret-key

Initform

(error "must supply secret key.")

Readers

secret-key (generic function)

Writers

(setf secret-key) (generic function)

Slot: api-token

Api token

Initargs

:api-token

Readers

api-token (generic function)

Writers

(setf api-token) (generic function)

Slot: api-version

Major version of the API.

Initargs

:api-version

Initform

1

Readers

api-version (generic function)

Writers

(setf api-version) (generic function)

Slot: api-url

Base url for API requests.

Initargs

:api-url

Initform

odesk::*api-base-url*

Readers

api-url (generic function)

Writers

(setf api-url) (generic function)

Slot: gds-url

Base GDS url for API requests.

Initargs

:gds-url

Initform

odesk::*gds-base-url*

Readers

gds-url (generic function)

Writers

(setf gds-url) (generic function)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *api-auth-url*

Package

odesk

Source

parameters.lisp (file)

Special Variable: *api-base-url*

Package

odesk

Source

parameters.lisp (file)

Special Variable: *gds-base-url*

Package

odesk

Source

parameters.lisp (file)

Special Variable: *library-name*

Package

odesk

Source

parameters.lisp (file)

Special Variable: *user-agent*

Package

odesk

Source

parameters.lisp (file)

6.2.2 Macros

Macro: def-gds REQUEST (&key URL METHOD VERSION SUB-URL) DOCSTRING

Package

odesk

Source

odesk.lisp (file)

Macro: def-req REQUEST (&key URL METHOD VERSION SUB-URL) DOCSTRING

Package

odesk

Source

odesk.lisp (file)

6.2.3 Functions

Function: format-url URL &key FROM-SUBS TO-SUBS

Package

odesk

Source

utils.lisp (file)

Function: get-page URL &key METHOD PARAMETERS

Package

odesk

Source

utils.lisp (file)

6.2.4 Generic functions

Generic Function: api-token OBJECT

Generic Function: (setf api-token) NEW-VALUE OBJECT

Package

odesk

Methods

Method: api-token (API api)

Method: (setf api-token) NEW-VALUE (API api)

Api token

Source

odesk.lisp (file)

Generic Function: api-url OBJECT

Generic Function: (setf api-url) NEW-VALUE OBJECT

Package

odesk

Methods

Method: api-url (API api)

Method: (setf api-url) NEW-VALUE (API api)

Base url for API requests.

Source

odesk.lisp (file)

Generic Function: api-version OBJECT

Generic Function: (setf api-version) NEW-VALUE OBJECT

Package

odesk

Methods

Method: api-version (API api)

Method: (setf api-version) NEW-VALUE (API api)

Major version of the API.

Source

odesk.lisp (file)

Generic Function: build-auth-url API &key FROB

Return authentication url to be used in browser..

Package

odesk

Source

odesk.lisp (file)

Methods

Method: build-auth-url (API api) &key FROB

Generic Function: data-format OBJECT

Generic Function: (setf data-format) NEW-VALUE OBJECT

Package

odesk

Methods

Method: data-format (API api)

Method: (setf data-format) NEW-VALUE (API api)

Data Format

Source

odesk.lisp (file)

Generic Function: encode-url API &key PARAMETERS

Encode url parameters.

Package

odesk

Source

odesk.lisp (file)

Methods

Method: encode-url (API api) &key PARAMETERS

Generic Function: gds-url OBJECT

Generic Function: (setf gds-url) NEW-VALUE OBJECT

Package

odesk

Methods

Method: gds-url (API api)

Method: (setf gds-url) NEW-VALUE (API api)

Base GDS url for API requests.

Source

odesk.lisp (file)

Generic Function: parse-page API PAGE

Parse fetched page.

Package

odesk

Source

odesk.lisp (file)

Methods

Method: parse-page (API api) PAGE

Generic Function: public-key OBJECT

Generic Function: (setf public-key) NEW-VALUE OBJECT

Package

odesk

Methods

Method: public-key (API api)

Method: (setf public-key) NEW-VALUE (API api)

Public key

Source

odesk.lisp (file)

Generic Function: secret-key OBJECT

Generic Function: (setf secret-key) NEW-VALUE OBJECT

Package

odesk

Methods

Method: secret-key (API api)

Method: (setf secret-key) NEW-VALUE (API api)

Secret key

Source

odesk.lisp (file)

Generic Function: sign-url API &key PARAMETERS

Sign url parameters.

Package

odesk

Source

odesk.lisp (file)

Methods

Method: sign-url (API api) &key PARAMETERS

Generic Function: url-read API URL &key PARAMETERS METHOD REQUEST-TYPE

Return parsed object.

Package

odesk

Source

odesk.lisp (file)

Methods

Method: url-read (API api) URL &key PARAMETERS METHOD REQUEST-TYPE

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types