THE API AN INTRODUCTION TO THE MINISTRYPLATFORM APPLICATION PROGRAMMING INTERFACE STEPHEN WAREHAM

WHAT DO YOU WANT TO DO? Build new/improved/customized features Build against extended/customized database Create brand new software applications What do YOU want to build using the API?

CUTTING THROUGH THE C.R.U.D C reate new records R ead data from the database U pdate existing database records D elete database records

ADDITIONAL API FEATURES Authenticate End Users Attach Files to Records

WHY USE THE API? The data access layer is built for you Data auditing is taken care of for you Workflow processes are invoked for you You “break the warranty” if you don’t! It’s fun and easy to do! No excuses!

WE HAVE 3 4 API S (TODAY) SOAP API: /ministryplatformapi/Api.svc Platform Service API: /ministryplatformapi/PlatformService.svc Data Service (ODATA) API: /ministryplatformapi/DataService.svc REST API (new!): /ministryplatformapi/ X …BUT WE’RE ABOUT TO HAVE 3 AGAIN

…HAS BEEN DEPRECATED!!! Create – AddRecord() Read – ExecuteStoredProcedure(), requires existing stored procedure Update – UpdateRecord() Delete – ExecuteStoredProcedure(), requires existing stored procedure X SOAP SCUM… ER, UM… CRUD…

…BUT DON’T WORRY We will still be supporting the SOAP API We will not remove the SOAP API anytime soon

PLATFORM SERVICE API Mirrors the “internal” API used by MinistryPlatform Uses OAuth for authentication Proprietary and often unconventional Steep learning curve

DATA SERVICE (ODATA) API Conforms to standard Open Data Specification ( Uses OAuth for authentication REST-ful interface (HTTP verbs, URL-based resources) Exposes entire database for better or worse

A SHINY, NEW, RESTFUL API!! Rest-ful syntax and HTTP verbs Secured access to the database Simple query mechanism Standard, easy to consume results OAuth for authentication

QUESTIONS? Next session: API Authentication and Authorization

AUTHENTICATION VS AUTHORIZATION Authentication validates a User Name and Password Typically results in TRUE or FALSE Authorization lets a user know what a user is allowed to do Typically results in a list of Roles or Rules Pertains to Nouns & Verbs: i.e. What do you see?, What can you do?

LEGACY SOAP API AUTHENTICATION Used GUID + API Password Must be passed as parameters with each request Must be stored securely by the Client Application One API User per Domain Full rights everywhere (or almost everywhere) Developers hold the “keys to the kingdom” But, don’t they anyway? Typically need database access to create stored procedures for all read operations

INTRODUCING OAUTH Open Authorization A standards-based authorization protocol Used by many major vendors (Facebook, Google, Twitter, …) More Info:

SECURITY TOKEN SERVICE/SERVER (STS) Has (or has access to) a user model Will authenticate a user and provide an Access Token The access token received is user-specific and temporary/time-limited Clients (software applications) utilize STS providers “Login to this App using your Facebook, Google, etc account” Eliminates the need for another user model MinistryPlatform is an STS consumer and provider!

GENERAL USE 1. User chooses to login using STS provider 2. User is redirected to provider’s login page 3. STS provider authenticates user 4. User is redirected back to original application along with an Access Token 5. Access Token is passed in Authorization Header of each subsequent request in order to gain access to Resources

OAUTH AND MINISTRYPLATFORM Use your Facebook account to log into MinistryPlatform Theoretically possible to log into Facebook using your MinistryPlatform account All 3 new APIs utilize OAuth for authentication/authorization

DEMO : CORE TOOLS & BATCH MANAGER Both use Client Credentials Authorization utilizes existing security roles, but is managed by the client application

USER INTERFACE = AUTHORIZATION 99% of the time you should use Client Credentials Use existing, empty roles for yes/no authorization Use end user’s credentials when building tools that make the user’s job easier They COULD do everything in MinistryPlatform (they have rights) They need a tool to give them a consolidated user interface to reduce the number of steps involved ?

QUESTIONS? Next Session: OAuth Flows

4 OAUTH FLOWS (STEPHEN’S DEFINITIONS) Implicit Grant – Used on the REST API test page, allows access from JavaScript Authorization Code Flow – Redirect to login page from server-side code Resource Owner Flow – User credentials are known/collected by the client application (no redirect) Client Credentials Flow – Uses credentials associated with the client application registered with the STS provider (MinistyPlatform)

IMPLICIT GRANT Can allow application to be developed entirely in client-side JavaScript Assumes end user has significant rights within MinistryPlatform Access Token belongs to the end user

AUTHORIZATION CODE Similar in end-user experience to Implicit Grant Redirects user to authorization server

RESOURCE OWNER Assumes your client application has (or can collect) the end user’s credentials Could be used like Client Credentials if you have a safe place for your application to store the user name and password (not recommended)

CLIENT CREDENTIALS (MY FAVORITE ) Allows client application to have access without storing a user name or password anywhere Can be used to provide data to an end user whether they are logged-in or not Best choice for 99% of your application development Client-specific user assignment is coming soon!

QUESTIONS? Reference with pretty diagrams : s.html s.html Next Session: REST API Overview

OFFICIAL NEW REST API (WOO HOO!) Available at root of API URL (e.g. /ministryplatformapi/) Has a built-in test page Utilizes Implicit Grant OAuth flow for test page DEMO: Login

GET Review endpoints to know what access your user has: /tables – Almost database tables (must have a Page record) /procs – API-specific Stored Procedures Demo: Do some getting!

POST Used to create records Can create an array of records in a single call Can create parent/dependent records in a single call Demo: Do some posting!

PUT Used to edit/update existing record Can also create a new parent record if necessary Demo: Do some putting!

DELETE Used to create new records. Just kidding. Can delete a list (array) of records in a single call Demo: Do some deleting!

QUESTIONS? Next session: Demo Application Part 1

DEMO APPLICATION PART 1 Introducing “QuickGive v1” Donation walkthrough Introduction to Stripe payments processor Explore use of Client Credentials to allow somebody we’ve never met to create a Donation record in our database Questions?

DEMO APPLICATION PART 2 REST API wrapper class overview Populating form drop-downs using simple GET operations Posting model to our controller Creating new Donation AND Donation Distribution records in a single API call Questions?

DEMO APPLICATION PART 3 Application summary Possible enhancements or other workflows Questions?

THANK YOU! Cell: