Best Practices

Best Practices in API

API Implementation Standards

1. Pre-Production Testing
   Always test and validate API requests in Postman or the built-in API Explorer before integrating them into the system.
   Test environments should mirror production configurations

2. Document Operations: The following table lists the key document operations, their endpoints, and any special requirements:

   Operation	Endpoint	Special Requirements
   Add Document	/docadd	Requires meta tags
   Delete Document	/docdelete	UID must exist
   Update Metadata	/updatemetadata	Supports custom fields

   Critical Notes:

   • File collection paths must use forward slashes (/) only.
   • Form authentication works only through docadd for WEB collections in SearchBlox.
   • Metadata is required when performing add operations.

3. Authentication & Headers

   • SB-PKEY header is required for all requests
   • API keys should follow these security practices:
     • Rotated quarterly
     • Store them securely and never place them in client-side code.
     • Restrict access by IP address whenever possible.

4. Error Handling

   Code	Typical Resolution
   400	Validate JSON structure and required fields
   401	Verify SB-PKEY matches Admin Console
   404	Confirm collection/document exists
   500	Check server logs and retry with backoff

5. URL Validation

   • Implement pre-flight checks for all provided URLs
   • Reject malformed URLs before API submission

6. Advanced Recommendations

   • Performance Optimization
   • Batch processing: Limit to 100 documents/request
   • Throttling: Implement 500ms delay between requests
   • Connection reuse: Maintain persistent HTTP connectio

Troubleshooting Checklist

1. Verify SB-PKEY matches Admin Console
2. Confirm collection exists
3. Validate JSON payload structure
4. Check network connectivity to SearchBlox server
5. Review server logs for detailed errors

🚧

Note:

• It is required to use SB-PKEY to attempt all SearchBlox REST API requests.
• SB-PKEY can be found on Dashboard->Administration->Users under the Private Key tab for each Admin role user.
• Admin role users will have access to Unique SB-PKEY.

Indexing and Collection Management

• Always verify that a collection exists and is correctly configured before making document add or delete API calls
• When indexing large datasets, use scheduled indexing rather than real-time API calls to reduce load on the server
• Use the Document Status API (/status) to confirm a document has been successfully indexed before relying on it in search results
• For collections using encryption, ensure the deid_ prefix is applied to all sensitive metadata fields before indexing — encrypted fields cannot be retroactively added without re-indexing
• Clear a collection using the /clear endpoint before re-indexing from scratch to avoid stale documents appearing in results