What's an API, you ask? The API (Application Programming Interface) is what allows different pieces of software to talk to each other. Think about all the times you've seen a Contact's information updated by the "API User." The API User shows up in the Audit Log because the API allowed the Add/Edit Family Tool to communicate with the Platform and update the Contact record. Think of the API as a waiter—it takes your order (the request), relays the order to the kitchen (the system), and returns your food (the response). Basically, the API takes a request, tells a system what to do, and returns a response.
More API information than you ever wanted to know? That's totally fine! You can still do all sorts of cool Platform extensions by partnering with a third party developer. We already have relationships with some great developers, so check out our integration partners to get started. And don't hesitate to reach out to Professional Services for help with the process.
Not enough API information? Excellent! The rest of this section is for you!
The REST (REpresentational State Transfer) API exposes MinistryPlatform data and features using a REST-ful interface (HTTP verbs and URL-based resources). The REST API is exposed at the root of the API Url. Find it by adding "/ministryplatformapi/" after your domain:
https://my.churchname.net/ministryplatformapi
The REST API uses OAuth 2.0 for authorization to the database. To use the OAuth 2.0 flow, credentials need to be specified on Administration > API Clients. While the Client Credentials grant flow, unless a user is explicitly specified using the $User keyword in each POST, PUT, or DELETE call, records created through the REST API are created using the user associated with the API client record. Security roles applied to that user are used to authorize requests regardless of what user is specified with the $User keyword.
Access to specific records and procedures is determined by Security Roles and considers Global Filters. Note: If a user has access to a page in the Platform, they also have access to the underlying Table.
Stored procedures can be configured by creating a record on System Setup > API Procedures. The user needs a security role that has access to the API Procedure. That can be added on the API Procedures subpage of the Security Roles page. See Professional Services for more information about we can help you partner with third party developers.
The REST API provides a simple query mechanism based on SQL queries, mirroring the platform data structure. Querying the API will give you a chance to show off your Advanced Search, Pages, Table, and View knowledge.
The REST API returns JSON (Javascript Simple Object Notation) for rapid development, ease of use, and compact serialization. This makes the data immediately useful in javascript, because JSON and javascript are closely related.
Excited to get started? You can immediately start interacting with the REST API using the built-in Swagger UI. Swagger exposes all of the REST end-points using an intuitive form-based User Interface.
The REST API can be accessed using a User login, in which case permissions are the User's. The API can also be accessed by an API Client, which inherits the permissions of a User designated in the API Client record.
The REST API uses standardized HTTP verbs to update, create, and read records for consistency and simplicity.
Endpoints represent the set of resources available for the API to read, update, and create. We're working to create documentation for our common endpoints and how they can be used. You can explore everything in Swagger now, but check back for additional information!
