linkedin

README

LinkedIn API Go Client

This Go package provides a thin client for making requests to LinkedIn APIs following the official LinkedIn API documentation.

⚠ This API client package is currently in beta and is subject to change. It may contain bugs, errors, or other issues that we are working to resolve. Use of this package is at your own risk. Please use caution when using it in production environments and be prepared for the possibility of unexpected behavior. We welcome any feedback or reports of issues that you may encounter while using this package.

Versioning

x.y.z

• x:
  • 0: under development
  • 1: production-ready
• y: breaking changes
• z: new functionality or bug fixes in a backwards compatible manner

Requirement

Go 1.19+

Features

• [x]: Supports Rest.li protocol version 2.0.0
• [x]: Supports LinkedIn versioned APIs
• [x]: 2-legged and 3-legged OAuth2 support
• [x]: Fine-grained control over all API calls using App and Session
• [x]: Extensive documentation and examples

License

© Mahir Hasan 2024

Released under the MIT license

Documentation

Overview

Package linkedin provides a thin client for making requests to LinkedIn APIs following the official LinkedIn API documentation.

Index

• Constants
• Variables
• type App
  • func New(clientID, clientSecret string) *App
  • func (app *App) ParseCode(code string) (Token, error)
  • func (app *App) Session(accessToken string) *Session
• type ContentDataType
• type HTTPClient
• type Header
• type Method
• type Params
• type RestLiMethod
• type Result
• type Session
  • func (session *Session) AccessToken() string
  • func (session *Session) App() *App
  • func (session *Session) Context() context.Context
  • func (session *Session) Get(uri string) (response *http.Response, data []byte, err error)
  • func (session *Session) Introspect(token string) (TokenData, error)
  • func (session *Session) RefreshToken(refreshToken string) (Token, error)
  • func (session *Session) SetAccessToken(token string)
  • func (session *Session) UseAuthorizationHeader()
  • func (session *Session) WithContext(ctx context.Context) *Session
• type Token
• type TokenData

Constants

const (
	OauthBaseURL     = "https://www.linkedin.com/oauth/v2"
	VersionedBaseURL = "https://api.linkedin.com/rest"
)

LinkedIn rest api base urls

See: https://learn.microsoft.com/en-us/linkedin/marketing/versioning?view=li-lms-2024-04

const (
	ListPrefix       = "List("
	ListSuffix       = ")"
	ListItemSep      = ","
	ObjPrefix        = "("
	ObjSuffix        = ")"
	ObjKeyValSep     = ":"
	ObjKeyValPairSep = ","
	LeftBracket      = "("
	RightBracket     = ")"
)

Rest.Li special characters

Variables

var RestLiMethodToHTTPMethodMap = map[RestLiMethod]Method{
	Get:                GET,
	BatchGet:           GET,
	GetAll:             GET,
	Finder:             GET,
	BatchFinder:        GET,
	Update:             PUT,
	BatchUpdate:        PUT,
	Create:             POST,
	BatchCreate:        POST,
	PartialUpdate:      POST,
	BatchPartialUpdate: POST,
	Action:             POST,
	Delete:             DELETE,
	BatchDelete:        DELETE,
}

RestLiMethodToHTTPMethodMap - map of LinkedIn Rest.Li methods to HTTP methods

Types

type App

type App struct {
	ClientID     string
	ClientSecret string
	RedirectURI  string
	// contains filtered or unexported fields
}

App holds the configuration for the LinkedIn application.

ClientID and ClientSecret: https://www.linkedin.com/developers/apps/{appID}/auth

func New

func New(clientID, clientSecret string) *App

New creates a new LinkedIn application and sets clientID and clientSecret.

func (*App) ParseCode

func (app *App) ParseCode(code string) (Token, error)

ParseCode redeems authorization code for access and refresh tokens.

See https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin%2Fcontext&tabs=HTTPS1

func (*App) Session

func (app *App) Session(accessToken string) *Session

Session creates a new LinkedIn session based on the app configuration.

type ContentDataType

type ContentDataType string

ContentDataType - HTTP content data type

const (
	URLEncoded ContentDataType = "application/x-www-form-urlencoded"
	JSON       ContentDataType = "application/json"
)

HTTP content data type

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (resp *http.Response, err error)
	Get(url string) (resp *http.Response, err error)
	Post(url string, bodyType string, body io.Reader) (resp *http.Response, err error)
}

HTTPClient is an interface to send http request. It is compatible with type `*http.Client`.

type Header

type Header string

Header - HTTP header data type

const (
	ContentType           Header = "Content-Type"
	Connection            Header = "Connection"
	RestLiProtocolVersion Header = "X-RestLi-Protocol-Version"
	RestLiMethodHeader    Header = "X-RestLi-Method"
	LinkedInVersion       Header = "LinkedIn-Version"
	Authorization         Header = "Authorization"
	UserAgent             Header = "user-agent"
	CreatedEntityID       Header = "X-RestLi-Id"
)

HTTP headers used in LinkedIn API requests

https://linkedin.github.io/rest.li/spec/protocol

https://learn.microsoft.com/en-us/linkedin/marketing/versioning?view=li-lms-2024-04#how-your-api-client-should-use-versioning

type Method

type Method string

Method - HTTP method for an API call.

const (
	GET    Method = "GET"
	POST   Method = "POST"
	PUT    Method = "PUT"
	DELETE Method = "DELETE"
)

HTTP API methods.

type Params

type Params map[string]interface{}

Params to construct the request payload.

type RestLiMethod

type RestLiMethod string

RestLiMethod - LinkedIn Rest.Li method type

const (
	Get                RestLiMethod = "GET"
	BatchGet           RestLiMethod = "BATCH_GET"
	GetAll             RestLiMethod = "GET_ALL"
	Finder             RestLiMethod = "FINDER"
	BatchFinder        RestLiMethod = "BATCH_FINDER"
	Create             RestLiMethod = "CREATE"
	BatchCreate        RestLiMethod = "BATCH_CREATE"
	Update             RestLiMethod = "UPDATE"
	BatchUpdate        RestLiMethod = "BATCH_UPDATE"
	PartialUpdate      RestLiMethod = "PARTIAL_UPDATE"
	BatchPartialUpdate RestLiMethod = "BATCH_PARTIAL_UPDATE"
	Delete             RestLiMethod = "DELETE"
	BatchDelete        RestLiMethod = "BATCH_DELETE"
	Action             RestLiMethod = "ACTION"
)

LinkedIn Rest.Li methods

type Result

type Result map[string]interface{}

Result - response body from LinkedIn API call request.

type Session

type Session struct {
	HTTPClient HTTPClient // HTTP client to send requests
	BaseURL    string     // set to override API base URL

	LinkedInVersion string // e.g. 202404
	// contains filtered or unexported fields
}

Session holds a LinkedIn session with an access token. Session should be created by App.Session.

func (*Session) AccessToken

func (session *Session) AccessToken() string

AccessToken returns current access token.

func (*Session) App

func (session *Session) App() *App

App returns associated App.

func (*Session) Context

func (session *Session) Context() context.Context

Context returns the session's context. To change the context, use `Session#WithContext`.

The returned context is always non-nil; it defaults to the background context. For outgoing LinkedIn API requests, the context controls timeout/deadline and cancellation.

func (*Session) Get

func (session *Session) Get(uri string) (response *http.Response, data []byte, err error)

Get sends a GET request to LinkedIn API and returns the response.

func (*Session) Introspect

func (session *Session) Introspect(token string) (TokenData, error)

Introspect checks the Time to Live (TTL) and status (active/expired) for the given token.

See: https://learn.microsoft.com/en-us/linkedin/shared/authentication/token-introspection?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2024-04&tabs=http

func (*Session) RefreshToken

func (session *Session) RefreshToken(refreshToken string) (Token, error)

RefreshToken redeems refresh token for new access and refresh tokens.

See: https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2024-04

func (*Session) SetAccessToken

func (session *Session) SetAccessToken(token string)

SetAccessToken sets a new access token.

func (*Session) UseAuthorizationHeader

func (session *Session) UseAuthorizationHeader()

UseAuthorizationHeader passes `access_token` in HTTP Authorization header.

func (*Session) WithContext

func (session *Session) WithContext(ctx context.Context) *Session

WithContext returns a shallow copy of session with its context changed to ctx. The provided ctx must be non-nil.

type Token

type Token struct {
	AccessToken           string `json:"access_token"`
	ExpiresIn             int64  `json:"expires_in"`
	RefreshToken          string `json:"refresh_token"`
	RefreshTokenExpiresIn int64  `json:"refresh_token_expires_in"`
	Scope                 string `json:"scope"`
}

Token - access and refresh tokens.

See: https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2024-04&tabs=HTTPS1#step-3-exchange-authorization-code-for-an-access-token

type TokenData

type TokenData struct {
	Active       bool   `json:"active"`
	ClientID     string `json:"client_id"`
	AuthorizedAt int64  `json:"authorized_at"`
	CreatedAt    int64  `json:"created_at"`
	Status       string `json:"status"`
	ExpiresAt    int64  `json:"expires_at"`
	Scope        string `json:"scope"`
	AuthType     string `json:"auth_type"`
}

TokenData - access and refresh token data after token inspection.

See: https://learn.microsoft.com/en-us/linkedin/shared/authentication/token-introspection?context=linkedin/context