Swagger UI
Swagger is an open-source software framework that aids in the design, build, and documentation of RESTful Web services based on the OpenAPI Specification. This guide provides instructions on how to access and interact with the Swagger UI, perform your first query, and execute subsequent queries.
The Swagger UI framework allows developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options.
Accessing the Swagger UI
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
Your First Query: Available Tables
Return all of the tables which are exposed to you via the REST api. This will depend on the security roles granted to your user.
-
Click GET /tables to expand this endpoint.
- Authorize use of the end-point.
In order to utilize the api, you must supply credentials proving you have permissions and set the scope for the end-point.
-
First, click the ON/OFF button to begin the process of Authorization/Authentication.
-
Second, select the "all" scope and select "Authorize".
-
Third, log in to the platform. You will be prompted for your username and password. This will Authorize you to use the REST api and determine which records (Pages) you have access to (via your Security Roles).
The end-point will be enabled if you log in successfully with the proper permissions.
-
- Run the query using the "Try it out!" button.
- Study the results.
The results will show in addition to the request url, response code, and headers. The Response Body is in JSON and will list all tables you have access to via your User permissions.
Your Second Query: Future Events
Return records for a specific table using the /table/{table}.
- Table: Any table returned by the previous query is a valid table.
- Fields: Any fields returned by the previous query are valid fields for the parent table. Any fields generated by the Advanced Search Tool are also valid, including the Table Lookup Convention.
- Filter: This is a valid SQL string representing the WHERE clause of a SQL query. Most SQL is supported here, but there are limits imposed by the API.
Example: Events
- Table = "Events"
- SelectFields = "Event_ID, Event_Title, Event_Start_Date, Event_End_Date, dp_fileUniqueId AS FileID"
- Filter = "Event_End_Date < GETDATE() AND Cancelled = 0 AND [_Approved] = 1"