REST API
The API (Application Programming Interface) is what allows different pieces of software to talk to each other. You know 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 take advantage of 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.
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 URL: https://{your platform domain}/ministryplatformapi
There are two ways to view and interact with the REST API.
On the next few pages, you can view and test API calls without leaving this site.
- Alternatively, the REST API is exposed at the root of the API URL (web address). To find your URL, add "/ministryplatformapi/" after your specific domain:
https://{your platform domain} /ministryplatformapi.A Swagger link is provided on the API landing page or can be accessed directly by adding "swagger" to the URL:
https://{your platform domain}/ministryplatformapi/swagger
Features
Secured Access to the Database
The REST API uses OAuth 2.0 for authorization to the database. To use the OAuth 2.0 flow, credentials need to be specified under . 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.
Stored Procedures
Stored procedures can be configured by creating a record on . The user needs a security role that has access to the API Procedure. That can be added on the API Procedures sub page of the Security Roles page. Professional Services can help you partner with third party developers.
Simple Query Mechanism
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.
Standard, Easy to Consume Results
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.
Swagger UI for Testing and Learning
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.
Security Roles and Permissions
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.
HTTP Verbs
The REST API uses standardized HTTP verbs to update, create, and read records for consistency and simplicity.
- GET: Read records.
- POST: Creates records or attaches files.
- PUT: Updates or edits an existing record.
Endpoint Documentation
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!
- Tables
- Procedures
- Files
- Communications, Messages, Texts
- Users (single sign-on)
- Tasks
- Refresh Meta Data