Difference between revisions of "API Method DirectAddressValidate"
(→Address-level Certificates) |
m (→Behind the Scenes) |
||
Line 7: | Line 7: | ||
== Behind the Scenes == | == Behind the Scenes == | ||
− | When a call is made to <code>/DirectAddressValidate</code>, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of | + | When a call is made to <code>/DirectAddressValidate</code>, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of certificate searches performed: |
=== Address-level Certificates === | === Address-level Certificates === | ||
− | + | The first certificate search looks for a certificate issued for the full recipient address: <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>. If all of the following are true, then <code>/DirectAddressValidate</code> will return <code>"validDirectAddress": true</code>: | |
* a certificate is found (either via DNS or LDAP) | * a certificate is found (either via DNS or LDAP) | ||
* the found certificate has not been revoked | * the found certificate has not been revoked | ||
− | * the found certificate is trusted or is signed by a trusted TrustAnchor | + | * the found certificate is trusted itself or is signed by a trusted TrustAnchor |
− | * the found certificate is not | + | * the found certificate is either: |
+ | ** not signed by DirectTrust or | ||
+ | ** signed by DirectTrust and the inquiring user's practice has been "vetted"<sup>1</sup> | ||
− | |||
=== Domain-level Certificates === | === Domain-level Certificates === | ||
− | + | If no trusted, non-revoked certificate can be found for the ''address'', the next certificate search will be performed on the ''domain'' of the intended recipient: <code>DrBobsPractice.OtherEHRDirect.com</code>. A Domain-level certificate is used for all users in a given domain. The same certificate will be used to sign messages from <code>DrBob@DrBobsPractice.OtherEHRDirect.com</code> and messages from <code>NurseRatchett@DrBobsPractice.OtherEHRDirect.com</code>. Since there ''aren't'' any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct-address exists is to confirm the existence of a trusted, non-revoked certificate for the ''domain''. | |
+ | |||
+ | |||
+ | IMPORTANT NOTE: ''A response from <code>/DirectAddressValidate</code> of <code>true</code> does '''not''' mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address or domain.'' For information about delivery confirmation, read about [[MDN processing]]. | ||
== Prerequisites == | == Prerequisites == |
Revision as of 07:59, 26 June 2014
Contents |
Description
The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.
Behind the Scenes
When a call is made to /DirectAddressValidate
, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of certificate searches performed:
Address-level Certificates
The first certificate search looks for a certificate issued for the full recipient address: DrTom@DrTomsPractice.MyEHRDirect.com
. If all of the following are true, then /DirectAddressValidate
will return "validDirectAddress": true
:
- a certificate is found (either via DNS or LDAP)
- the found certificate has not been revoked
- the found certificate is trusted itself or is signed by a trusted TrustAnchor
- the found certificate is either:
- not signed by DirectTrust or
- signed by DirectTrust and the inquiring user's practice has been "vetted"1
Domain-level Certificates
If no trusted, non-revoked certificate can be found for the address, the next certificate search will be performed on the domain of the intended recipient: DrBobsPractice.OtherEHRDirect.com
. A Domain-level certificate is used for all users in a given domain. The same certificate will be used to sign messages from DrBob@DrBobsPractice.OtherEHRDirect.com
and messages from NurseRatchett@DrBobsPractice.OtherEHRDirect.com
. Since there aren't any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct-address exists is to confirm the existence of a trusted, non-revoked certificate for the domain.
IMPORTANT NOTE: A response from /DirectAddressValidate
of true
does not mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address or domain. For information about delivery confirmation, read about MDN processing.
Prerequisites
1 This API call requires Vendor-level credentials. The credentials should be populated into the applicationId
and applicationPassword
fields of the auth
block:
{ ... "auth": { "applicationId": "vendorId", "applicationPassword": "vendorPassword", "accountId": "", "userId": "" } }
Code Samples
Language | Source Code Examples |
---|---|
C# | public void TalkToUpdox() { string json = new JavaScriptSerializer().Serialize(new { recipient = "DrTom@DrTomsPractice.MyEHRDirect.com", // required auth = new { applicationId = "vendorId", applicationPassword = "vendorPassword", accountId : "accountId", userId: "userId" } }); string url = "https://updoxqa.com/io/directAddressValidate"; SendReceiveJSON(json, url); } private void SendReceiveJSON(string json, string url) { var httpWebRequest = WebRequest.Create(url); httpWebRequest.ContentType = "application/json"; httpWebRequest.Method = "POST"; using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream())) { streamWriter.Write(json); streamWriter.Flush(); streamWriter.Close(); var httpResponse = (HttpWebResponse) httpWebRequest.GetResponse(); using (var streamReader = new StreamReader(httpResponse.GetResponseStream())) { var result = streamReader.ReadToEnd(); } } } |
Java |
import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.DefaultHttpClient; import org.apache.http.util.EntityUtils; import java.util.HashMap; import java.util.Map; public class UpdoxTest { public void TalkToUpdox() throws Exception { String uri = "https://updoxqa.com/io/directAddressValidate"; ObjectMapper mapper = new ObjectMapper(); Map<String,Object> messageData = BuildMessage(); String jsonData = mapper.writeValueAsString(messageData); HttpResponse httpResponse = SendReceiveJSON(jsonData, uri); HttpEntity responseEntity = httpResponse.getEntity(); String response = EntityUtils.toString(responseEntity); JsonNode actualObj = mapper.readTree(response); System.out.println(actualObj.get("responseCode")); System.out.println(actualObj.get("responseMessage")); } private Map<String,Object> BuildMessage() throws Exception { Map<String,Object> messageData = new HashMap(); Map<String,String> authData = new HashMap(); messageData.put("recipient", "DrTom@DrTomsPractice.MyEHRDirect.com"); Map<String,Object> authData = new HashMap(); authData.put("applicationId", "vendorId"); authData.put("applicationPassword", "vendorPassword"); authData.put("accountId", "accountId"); authData.put("userId", "userId"); messageData.put("auth", authData); messageData.put("auth", authData); return messageData; } private HttpResponse SendReceiveJSON(String jsonData, String uri) throws Exception { HttpClient httpClient = new DefaultHttpClient(); HttpResponse response = null; StringEntity params = new StringEntity(jsonData); try { HttpPost request = new HttpPost(uri); request.addHeader("content-type", "application/json"); request.setEntity(params); response = httpClient.execute(request); } catch (Exception ex) { // handle exception here } finally { httpClient.getConnectionManager().shutdown(); } return response; } } |
Messages
Destination Address
Request JSON
{ "recipient": "DrTom@DrTomsPractice.MyEHRDirect.com", "auth": { "applicationId": "vendorId", "applicationPassword": "vendorPassword", "accountId": "", "userId": "" } }
HTTP Response Status
200 OK
Response JSON
{ "successful": true, "responseMessage": "OK", "responseCode": 2000, "recipient": "contact:171099", "name": "DrTom@DrTomsPractice.MyEHRDirect.com", "directAddress": "DrTom@DrTomsPractice.MyEHRDirect.com", "validDirectAddress": true, "vettingRequired": false, "reason": null }
Relevant Response Codes
In addition to the General Error Set, this method may return the following values in the responseCode
and responseMessage
fields:
responseCode
|
responseMessage
|
---|