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. To find it, add "/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 add "swagger" to the URL to access it directly:
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, specify credentials under . While the Client Credentials grant flow, unless a user is explicitly specified using the $User keyword in each POST, PUT, or DELETE call, you create records through the REST API using the user associated with the API client record. Use the security roles applied to that user to authorize requests regardless of what user is specified with the $User keyword.
Security roles determine access to specific records and procedures, and they consider global filters.
Stored Procedures
To configure stored procedures, create a record on . The user needs a security role with access to the API Procedure. Add this 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. Query the API for 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 interact 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
Access the REST API using a User login, which uses the User's permissions. You can also access the API through 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