Getting started with APIs

Getting started with APIs ACCESS pre-conference workshop/hackfest Halifax, NS, October 23, 2023 Thomas Guignard Outline •Introductions and roundtable •General principles of APIs •What are they used for •How do they work •How can they be used •Tools for exploring APIs •Have fun with APIs! •Wrap-up Introductions •Who are you? •What’s your experience with APIs? •What projects would you like to use APIs for? •Which API would you like to learn more about today? GET https://api.ingeniumcanada.org/collection/v1/search?query=halifax%20explosion { "total": "5", "offset": "0", "limit": "100", "docs": [ { "id": "1973.0238.001", "itemType": "obj", "objCatalogueNumber": "1973.0238", "objGeneralDescription": "METAL, SYNTHERIC & WOODCONSTRUCTION. PT CASE IS GLASS & METAL", "objAquisition_Year": 1973, "objAquisition_Number": 238, "objRecord_Created": "1973-04-01T19:16:00Z", "objRecord_CreatedEpoch": 102539760, "objRecord_LastUpdated": "2022-11-08T04:18:00Z", "objRecord_LastUpdatedEpoch": 1667881080, "objName": "Switching system", "objType": "AUTOMATIC", "objModel": "KEITH LINE SWITCH", "objPart_Total": 1, "objPart_Number": 1, "objManufacturer_Name": "Automatic Electric Co.", "objManufacturer_Acronym": "Automatic Electric", "objManufacturer_Country": "United States of America", "objManufactured_DateFrom": 1924, "objManufactured_DateQualifier": "circa", "objOnDisplay": false, "objDetails_Markings": "\" L 10 \" STENCILLED IN BLACK ON FRAME. NUMEROUS MARKINGSNOT ACCESSIBLE AT TIME OF RE-CATALOGUING. (1997.01.09)", "objDetails_Missing": "UNKNOWN", What are APIs? Server Client Application User … Database … Request Response Application Programming Interface Public vs private APIs ServerClients ServerClient Public or open API Private or internal API Public vs private APIs •Public APIs, aka open APIs or external APIs •Data exchange with third parties •Often used in open data projects (e.g. open government, linked data) •Not necessarily free •Can be restricted and require authentication •Internal (or private) APIs •Data exchange within a system or organization •Example: web frontend interacting with a database API architecture types •REST (REpresentational State Transfer) •Originally describes a type of software architecture, of which APIs are only an element •RESTful APIs have become the norm •Payload can be JSON or XML/HTML •SOAP (Simple Object Access Protocol) •Older API protocol, less used nowadays •XML payload •Strict data structure and communication rules •RPC (Remote Procedural Call) •Predecessor of SOAP and RESTful RESTful API principles 1. Client-server architecture 2. Layered 3. Uniform interface 4. Stateless 5. Cacheable 6. Code on demand each side is independent server complexity hidden from client standard, documented format each request exists on its own responses can be cached server can delegate logic to the client HTTP Methods GET for reading data POST for sending/creating data (new record) PUT for updating existing data (existing record) PATCH for updating certain fields only (existing record) DELETE for removing data Token-authenticated request GET https://api.ingeniumcanada.org/collection/v1/search?query=halifax%20explosion Authorization: Bearer 123456789123456789123456789 User-Agent: PostmanRuntime/7.33.0 Accept: */* Cache-Control: no-cache Postman-Token: 67d8d9f1-c735-463a-be71-f9ffcbf9f255 Host: api.ingeniumcanada.org Accept-Encoding: gzip, deflate, br Connection: keep-alive PathBase URL Query parameter Method Headers (no body) API documentation examples Available endpoints Sample queries Parameter details Sample responses API documentation examples Interactive test query builder Parameter details Authentication API documentation examples Available endpoints Sample queries Sample responses API Etiquette •Get your own keys •Specify the User-Agent header •Include contact info (URL and/or mailto) •Get included in the “polite pool” •Avoid overwhelming the server •Cache responses when possible •Request only required data •Pause between requests Tools for exploring •Web browsers •Enough for simple testing of GET requests •Chrome: consider plugins such as JSONFormatter or JSONVue •Safari: consider plug-ins such as JSON Peep •Firefox and Edge have built-in JSON viewers •Postman •More powerful features •Supports POST, PUT requests •Easier authentication with variables and token management •Available as standalone app or in the browser Some examples •Crossref – api.crossref.org •Open Library – openlibrary.org/developers/api •Open Alex – api.openalex.org •Semantic Scholar – api.semanticscholar.org •arXiv – export.arxiv.org/api •Canadian Open Government Portal •SPARQL endpoints, e.g. query.wikidata.org •OAI-PMH, Alma/Primo API,… Time to have fun! API integration workshop ACCESS pre-conference workshop/hackfest Halifax, NS, October 23, 2023 Thomas Guignard WiFi: PG Public pw: diamond How to go further •Postman/browser good for exploring but not for repetitive tasks •Batch editing tools •OpenRefine •Google Sheets (via custom functions) •Python / Jupyter notebook (eg via requests library) •Shell / bash scripts with curl or wget •No-code automation tools •E.g. Make, n8n, Relay… •Web integration •Custom enrichments in Primo •Live occupancy display on library website (or catalogue), etc. Check your data for privacy requirements before using cloud apps…