DFws API User Guide

Release 5.2.0

All rights reserved. No part of this publication may be re-transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of DF/Net Research, Inc.. Permission is granted for internal re-distribution of this publication by the license holder and their employees for internal use only, provided that the copyright notices and this permission notice appear in all copies.

The information in this document is furnished for informational use only and is subject to change without notice. DF/Net Research, Inc. assumes no responsibility or liability for any errors or inaccuracies in this document or for any omissions from it.

All products or services mentioned in this document are covered by the trademarks, service marks, or product names as designated by the companies who market those products.

Google Play and the Google Play logo are trademarks of Google LLC. Android is a trademark of Google LLC.

App Store is a trademark of Apple Inc.

Nov 01, 2019


This guide describes the DFdiscover application programming interface, commonly known as the DFws API, or simply DFws.

The DFdiscover API is a programming resource for users who would like to extend DFdiscover or build connectors from other environments to DFdiscover. Use or understanding of the DFws is not required for successful use of DFdiscover. Most users will never use DFws. This guide is intended for programmers.

Table of Contents

1. Getting Help
2. Conventions
1. Introduction
1.1. What is DFws?
1.2. How does it work?
1.3. How can we use it?
2. Quick Start with DFws
2.1. Just the Essentials
2.2. PHP Example
3. Developing with DFws
3.1. Prerequisites
3.2. API Client Account
3.3. DFdiscover and DFws API
3.3.1. Sessions
3.4. Getting Started
3.4.1. Authorize request
3.4.2. Subsequent Requests
3.4.3. Logout Request
3.4.4. API Endpoints (Resources)
3.5. Status Codes
3.5.1. Errors
3.6. JWT Code Samples
3.7. Details of all supported API endpoints
3.7.1. Session Management
3.7.2. Study Setup
3.8. Study Data
3.8.1. List of Role names
3.8.2. Subject list
3.8.3. Keys for Subject
3.8.4. Subject Binder
3.8.5. Keys Available by Site
3.8.6. Status for keys
3.8.7. Database Records by filter
3.8.8. Database record by keys
3.8.9. Database record by name
3.8.10. Unlock
3.8.11. Lock
3.8.12. Add/Update Record
3.8.13. Queries by site
3.8.14. Queries/Reasons count
3.8.15. Visits
3.8.16. Visit date
3.9. Document Management
3.9.1. Get Document
3.9.2. Add Document
3.10. User / Permission / Role Management
3.10.1. User Profile
3.10.2. Change Password
3.10.3. Verify Password
3.10.4. User Account
3.10.5. User Roles
3.10.6. Study Roles
3.10.7. Role Permissions
3.11. Metrics
3.11.1. License Metrics
3.11.2. Feature Metrics
4. Administering DFws
4.1. Installing DFws
4.2. Configuration File (dfws.cf)
4.3. DFws System Database (dfws.db)
4.3.1. DF_DEVELOPERS (Table Definition)
4.3.2. DF_LOG (Table Definition)
4.4. Starting and Stopping DFws
4.5. Monitoring DFws Activities
4.5.1. Using DFwsadmin
4.5.2. API Client Account Management
4.5.3. Log Management
4.5.4. System Status
A. Copyrights - Acknowledgments
A.1. External Software Copyrights
A.1.1. DCMTK software package
A.1.2. Jansson License
A.1.3. Mimencode
A.1.4. RSA Data Security, Inc., MD5 message-digest algorithm
A.1.5. mpack/munpack
A.1.6. TIFF
A.1.7. PostgreSQL
A.1.8. OpenSSL License
A.1.9. Original SSLeay License
A.1.10. gawk
A.1.11. Ghostscript
A.1.12. MariaDB and FreeTDS
A.1.13. QtAV
A.1.14. FFmpeg
A.1.15. c3.js
A.1.16. d3.js