Recommended
More Related Content
What's hot
What's hot (9)
Similar to API Developer Training: Insights for Integrations
Similar to API Developer Training: Insights for Integrations (20)
More from JeremyOtt5
More from JeremyOtt5 (16)
Recently uploaded
Recently uploaded (14)
API Developer Training: Insights for Integrations
- 1. API Developer Training: Insights for Integrations Ted Soper ted.soper@bullhorn.com Barry Shevlin barry.shevlin@bullhorn.com Ethan Schroeder ethan.schroeder@bullhorn.com
- 3. API Features & Code Examples
- 4. BULLHORN API AUTHENTICATION ● OAUTH 2.0 ● Registration ● Shared key - Best practice ● Individual Key - Per case basis only
- 5. BULLHORN OAUTH Use username, password redirect URI to get AuthCode Get Auth Code Use Auth Code to get Access Token & Refresh Token Use Access Token to get Rest Token Get Rest Token Use Refresh token to get new Rest Token Refresh Rest Token Send Username to get Oauth URL & Rest URL Get Rest URL Get Access Token
- 6. BULLHORN OAUTH rest.bullhornstaffing.com/rest- services/loginInfo?username=username Get Rest URL 1. Get Rest URL 2. Get Auth Code 3. Get Access Token 4. Get Rest Token > Refresh Rest Token ● Returns the Rest URL & Auth URL for the Account ● Check for Datacenter API URLS http://bullhorn.github.io/Data-Center-URLs/
- 7. BULLHORN OAUTH /authorize?client_id=clientId&response_type=code &action=Login&username=username&password=password &redirect_uri=redirectUrl GET Auth Code /token?grant_type=authorization_code&code=authCod e&client_id=clientId&client_secret=clientSecret&r edirect_uri=redirectUrl POST for Access Token 1. Get Rest URL 2. Get Auth Code 3. Get Access Token 4. Get Rest Token > Refresh Rest Token /login?version=*&access_token=accessToken GET Rest Token
- 8. BULLHORN OAUTH /token?grant_type=refresh_token &refresh_token=refreshToken&client_id=clientId &client_secret=clientSecret Refresh Rest Token 1. Get Rest URL 2. Get Auth Code 3. Get Access Token 4. Get Rest Token > Refresh Rest Token ● Default REST token lasts for 10 minutes ● Get a new REST token with a Refresh request
- 9. Entities & Metadata Best Practices
- 10. Entity Lookup ● /search ○ Lucene-based search ○ Available for most common entities ○ Faster than Query ● /query ○ JPQL (SQL-like) querying ○ Use when search isn’t available ● /find (FastFind) ○ Searches several entities in one request ○ Useful with user input /search/ClientContact ?query=(clientCorporation.id:123) &fields=name,id,status /query/CorporateUser ?where=(name='Ted Soper’) &fields=id,email /find ?query=monster &countPerEntity=3
- 11. Entity Pagination /search/...&count=500&start=0 Get first page { data: [500], total: 1700 } Get total from response /search/...&count=500&start=500 Get remaining pages in parallel /search/...&count=500&start=1000 /search/...&count=500&start=1500 ● Count ○ How many objects to return ○ Default: 30 ○ Max: 500 ● Start ○ How many objects to skip ○ Default: 0 1 2 3
- 12. Efficient Lookups ● Only get the fields you need ● Avoid “fields=*” ● Exception: one-time metadata calls ● Don’t duplicate requests ● Use /search if possible ● If you only need the count, leave off fields/layout /entity/JobOrder/1234/notes ?fields=comments,action Get notes for one entity /search/ClientContact ?query=firstName:Barry Search for list of IDs & count
- 13. Metadata Lookup ● Full structural data about an entity ● Field constraints ● Reference types ● Custom field definitions ● Job track information /meta/Candidate ?fields=* &meta=basic Lookup before creation /entity/JobOrder/12345 ?layout=RecordEdit &meta=track Add to another request
- 14. Metadata Example Responses [ { "name": "assignedUsers", "type": "TO_MANY", "label": "Assigned to", "optionsType": "CorporateUser", "optionsUrl": "/options/CorporateUser", "associatedEntity": { "entity": "CorporateUser", "entityMetaUrl": "/meta/CorporateUser", "label": "Corporate User", "fields": [...] } }, {...}, {...} ] Reference Field [ { "name": "customText3", "type": "SCALAR", "dataType": "String", "maxLength": 100, "label": "Primary Department", "options": [ { "value": "Boston MA Dept", "label": "Boston MA Dept" }, { "value" : "Orlando FL Dept", "label" : "Orlando FL Dept" } ] }, {...} ] Custom Field w/ Options
- 16. Subscriptions for data sync PUT Subscription New Change Events get logged against sub GET Subscription updates GET Subscription updates New Change Events get logged against sub ● Create a Subscription based on data change events ○ Entity create/update ○ Field map change ○ Job match search
- 17. Subscriptions for data sync ...event/subscription/MySubName?type=entity&names=Candidate &eventTypes=INSERTED,UPDATED,DELETED Example ● Parameters ○ type ○ (entity)names ○ eventTypes
- 18. Custom Tabs
- 19. Custom Tabs ● Custom Tab ○ Pulls in an iframe application ○ Appbridge user send request from extension to Bullhorn ○ Through appbridge make requests to the bullhorn api
- 20. BULLHORN OAUTH & Custom Tabs /token?grant_type=authorization_code&code=authCod e&client_id=clientId&client_secret=clientSecret&r edirect_uri=redirectUrl POST for Access Token1. Get Access Token 2. Get Rest Token > Refresh Rest Token /login?version=*&access_token=accessToken GET Rest Token Grab Auth Code from the CustomComponent/redirect Use Auth Code from App Bridge
- 22. Rate Limiting 429 - “Too Many Requests” ● You have a bucket of API requests per minute ● Don't throw your request away, just wait 1 second and retry! ● Multiple apps should have multiple keys. *This is NEW! - if you have an existing app talk to Bullhorn support if you have questions.
- 23. Questions?
Editor's Notes
- Schedule: 00-7: Intro & REST Overview (Ted) 7-40: Code Examples (5-6 mins per) (Ted & Barry) 40-45: QA (Ethan Lead as SME) Intros: Ted Soper: original employee of Fyre, Principle Engineer over many of the Addon & Customer Experience products working with Barry Shevlin: First intern (and only) at Fyre and now Backend Software engineer working on Fyre Sync, Sync Submittals Ethan Schroeder: Enterprise Software Arch at Bullhorn, 5.5yrs Our Time at Fyre Between us we’ve integrated 25 different ATS systems, including BUllhorn and Bullhorn for Force 1 sentence on Fyre and how much integration we have done with bullhorn Ethan has touch every part of the API and core system at bullhorn
- @ted Lead Why It is Great Depth of Features Same API Bullhorn Internal Engineering Teams use it for all our addons including Novo is the same API you all have access to Metadata API allows you to make intelligent and thorough solutions The powerful Subscription service allows you to set watchers on all sorts of data in the bullhorn ats Activity logs means users can audit what Application partners update/add to their system Documentation & Resources Open and detailed API Docs Currently 44 Public repositories on github including libraries and examples Support Forum History of thousands of posts with Bullhorn technical staff available to answer API use questions
- *Roughly 5 minutes per example
- TED Shared key: Each app has one client Key All corps using partner app use the same API key Best practice for integrator Don't share across apps Individual keys per corp More bookkeeping for you & us Able to silo troubled accounts/deployments Shared key Best practice for integrator Don't share across apps Individual Key More bookkeeping for you & us Able to silo troubled accounts/deployments Per case basis only
- TED I still see some ATS APIs using basic auth, static auth or even no auth. OAUTH 2 requires a little extra work but bullhorn makes it easy and secure
- TED Ted: First thing to do is get the Rest URL and Auth URL that you will use for all other API calls. To do this you send the API User Username to the login Info Endpoint
- TED Next up is the core of the process Getting the Auth Code with ClientId, Username, password and the redirect URL of your APP With the AUthcode you’ll send it and the ClientId & Client Secret to get your Access Token Lastly you’ll get a short lived REST Token to actually make you API calls
- TED By default the REST Token lasts for 10 minutes, instead of going through steps 2-4 again you can just use your refresh token from step #3 and get a new REST token with 1 call. If all goes right you wont need to do steps 1-4 again.
- BARRY The bulk of a lot of integrations with the Bullhorn API will be centered around entity lookup and modification. API is full of so many features, it’s hard to know when to use each one
- BARRY Search is best practice most often Query is very limited use case, used for small entities like Skills or candidateEducation Find when you don’t know what entity you want to lookup
- BARRY Normally you receive 30 results When querying for a large number of objects, your results might not fit into one response. With count parameter it can be expanded up to 500 in one request (300 for options). For more than 500, pagination is needed Total on first response Subsequent pages can be parallel in groups of 500
- BARRY Making efficient Entity requests Talk about performance degradation with * Sends every single field, even custom fields that aren’t used A lot more strain on the network layer Especially important if you’re retrieving a large number of objects Leaving off fields/layout returns a list of IDs and count, and is significantly faster For a single candidate you can populate all associated records lookup Instead of sending fields you can hand in a layout; show exactly the fields that appear in the UI
- BARRY One of the most powerful features of the API What Novo uses to determine what to display Field constraints see type of a field, (number, string, date, etc.), as well as valid ranges Can see field specialty, like currencies Reference types - see if a field references another entity URL to retrieve options Custom field definitions Labels, Types, references, etc. Job track information `meta=track` to retrieve metadata for a JobOrder’s job track Retrieve an entity with its metadata attached, see the object as it is in the UI - more or less
- BARRY Reference field Field label Url to retrieve options Reference metadata Custom field w/ options Field label Constraints List of all options for scalars
- Ted TODO add intro
- TED Set watcher lists to collect change events Lets you get entity events, field map change events, and job match search events. //OLD NOTES *Suggested by Sam Emmons - Ted is dumb on this topic. Will work with Barry till we hit a road block. Subscriptions for data sync vs. selecting everything by date range Talk about subscription model and how to use it Talk about how to coordinate with support on initial data seeds / bootstrap operations. Candidate update events - all the updates that came through since your last request. Reget allows you to pull items you already got. Transaction ID will allow you to query edit history
- TED Set the Name: Create a unique name to identify the subscription Set the type=entity And names of the typesnames=Candidate And the events you care about&eventTypes=INSERTED,UPDATED,DELETED
- Ted TODO add intro
- TED Custom Component Redirect When navigating to the custom component in Bullhorn, a call will be made to the CustomComponent/redirectservice. That service will generate the proper endpoint for the custom component. The generated endpoint will include the following: EntityType UserID CorporationID PrivateLabelID EntityID currentBullhornUrl authCode Use the authcode to establish connection http://bullhorn.github.io/REST-Backed-Custom-Components/ Preview panels Custom component - suggested
- TED Next up is the core of the process Getting the Auth Code with ClientId, Username, password and the redirect URL of your APP With the AUthcode you’ll send it and the ClientId & Client Secret to get your Access Token Lastly you’ll get a short lived REST Token to actually make you API calls
- Ted TODO add intro
- Talk up the controls You have a bucket of requests per your licensing model If you are a marketplace partner you have a budget per org Don't throw your request away, just wait 1 second! Multiple apps should have multiple keys.
- Put links to resources in this deck at the end