300 likes | 370 Views
In these slides, you'll learn about some of the most common mistakes we've seen when building API calls. If you're using an API to set up address autocomplete on your forms, this is the presentation for you.<br><br>You can learn more about Smarty's APIs by visiting: https://www.smarty.com/docs/cloud
E N D
Common Mistakes When Calling Smarty APIs Status Codes 401 and 402
In today’s webinar, we’ll cover two types of mistakes: “Authentication Required” errors — status code 401 “Payment Required” errors — status code 402
“Authentication Required” Errors — Status Code 401 In this section: How to authenticate API requests the right way Common mistakes in client-side requests Common mistakes in server-side requests
How to Authenticate API Requests the Right Way • Get familiar with your account's API Keys page.
How to Authenticate API Requests the Right Way • Get familiar with your account's API Keys page. • Understand the difference between client-side requests (in a web browser) and server-side requests. Since browsers send a Referer header automatically, our system treats any request that includes a Referer header as a client-side request. In contrast, if the request does NOT have a Referer header, our system treats it is a server-side request.
How to Authenticate API Requests the Right Way • Get familiar with your account's API Keys page. • Understand the difference between client-side requests (in a web browser) and server-side requests. Since browsers send a Referer header automatically, our system treats any request that includes a Referer header as a client-side request. In contrast, if the request does NOT have that header, our system treats it is a server-side request. • For client-side calls: • Include an embedded key in the request URL: key=31050191824945 • Make sure that the Referer value sent by the browser is listed as a host for the embedded key being used.
How to Authenticate API Requests the Right Way • Get familiar with your account's API Keys page. • Understand the difference between client-side requests (in a web browser) and server-side requests. Since browsers send a Referer header automatically, our system treats any request that includes a Referer header as a client-side request. In contrast, if the request does NOT have that header, our system treats it is a server-side request. • For client-side calls: • Include an embedded key in the request URL: key=31050191824945 • Make sure that the Referer value sent by the browser is listed as a host for the embedded key being used. • For server-side calls: • Include the secret keys (auth-id and auth-token) in the request URL: auth-id=a1Gf2rC&auth-token=HH3tnV
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request.
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request. • Don't list the wrong referer/host value with the embedded key. (Look between the slashes of the referer value.)
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request. • Don't list the wrong referer/host value with the embedded key. (Look between the slashes of the referer value.) • For localhost, just list "localhost" without the port number. • For calls from the jsfiddle website, the correct host is fiddle.jshell.net
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request. • Don't list the wrong referer/host value with the embedded key. (Look between the slashes of the referer value.) • For localhost, just list "localhost" without the port number. • For calls from the jsfiddle website, the correct host is fiddle.jshell.net • When using a wildcard in a hostname, don't use the * for more than one level of subdomain. For example: complete referer value: www.accounts.smarty.com correct: *.accounts.smarty.com incorrect: *.smarty.com
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request. • Don't list the wrong referer/host value with the embedded key. (Look between the slashes of the referer value.) • For localhost, just list "localhost" without the port number. • For calls from the jsfiddle website, the correct host is fiddle.jshell.net • When using a wildcard in a hostname, don't use the * for more than one level of subdomain. • Don't forget to explicitly set up a Referer header when calling from a mobile app or when using an embedded key in Postman. (Mobile apps and Postman don't send a Referer header by default, so you will need to set one up manually.)
Common Mistakes in Client-Side Requests • Don't submit secret keys in a client-side request. • Don't list the wrong referer/host value with the embedded key. (Look between the slashes of the referer value.) • For localhost, just list "localhost" without the port number. • For calls from the jsfiddle website, the correct host is fiddle.jshell.net • When using a wildcard in a hostname, don't use the * for more than one level of subdomain. • Don't forget to explicitly set up a Referer header when calling from a mobile app or when using an embedded key in Postman. (Mobile apps and Postman don't send a Referer header by default, so you will need to set one up manually.) • Don't forget to URL-encode the request URL. For example, a # symbol that is not URL-encoded will break up the request URL, and our system will not recognize any part of the URL after the # symbol.
Common Mistakes in Server-Side Requests • Don't send an embedded key in a server-side request.
Common Mistakes in Server-Side Requests • Don't send an embedded key in a server-side request. • Don't type the auth-id or auth-token by hand; you might mistype a 1 for a lower-case lor a 0 for a capital O.
Common Mistakes in Server-Side Requests • Don't send an embedded key in a server-side request. • Don't type the auth-id or auth-token by hand; you might mistype a 1 for a lower-case l or a 0 for a capital O. • Don't forget to URL-encode the request URL.
“Payment Required” Errors — Status Code 402 In this section: Understanding your Smarty account and your licenses Common mistakes that result in a "Payment Required" error
Understanding Your Smarty Account and Your Licenses • If you are a developer trying to work with the Smarty APIs, we recommend that you be able to log in to the Smarty account you are trying to use. Currently, each Smarty account has only a single login email and password, so you would need to obtain those login details from whomever has them.
Understanding Your Smarty Account and Your Licenses • If you are a developer trying to work with the Smarty APIs, we recommend that you be able to log in to the Smarty account you are trying to use. Currently, each Smarty account has only a single login email and password, so you would need to obtain those login details from whomever has them. • Be familiar with the different pages available in your account, especially the Subscriptions and API Keys pages.
Understanding Your Smarty Account and Your Licenses • If you are a developer trying to work with the Smarty APIs, we recommend that you be able to log in to the Smarty account you are trying to use. Currently, each Smarty account has only a single login email and password, so you would need to obtain those login details from whomever has them. • Be familiar with the different pages available in your account, especially the Subscriptions and API Keys pages. • Make sure you understand your licenses. Know which APIs they allow you to call and what specific abilities are included. Because we offer so many different licenses, distinguishing them can be tricky. Feel free to ask the Support team or your sales rep about the abilities of any particular license.
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. Many companies have multiple Smarty accounts — for example, a production account and several accounts used by individual developers. Make sure the auth credentials you are submitting in the request URL pertain to the account that actually has the right subscription in it.
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. • Don't try to call an API that is not supported by one of your licenses. Example: You try to call the US Autocomplete Pro API, but you only have a US Address Verification subscription, with a US Core Edition license. (Our US Autocomplete service requires its own license.)
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. • Don't try to call an API that is not supported by one of your licenses. • If using one of our SDKs, don't assume that the license value listed in the Github example code is the right one. Example: The default license listed in the Github example code is us-rooftop-geocoding-cloud, but you don't actually have a Rooftop Geocoding license. You may need to change the license value to us-core-cloud or us-standard-cloud. This line is from the JavaScript SDK: let clientBuilder = new SmartyCore.ClientBuilder(credentials) .withBaseUrl("YOUR URL").withLicenses(["us-rooftop-geocoding-cloud"]);
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. • Don't try to call an API that is not supported by one of your licenses. • If using one of our SDKs, don't assume that the license value listed in the Github example code is the right one. • Don't try to use an ability that doesn't pertain to your specific license. Examples: • When calling our US Street Address API, you include match=enhanced, but you don't have a US Core Edition license. You only have the older US Standard Edition license (which doesn’t include enhanced matching).
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. • Don't try to call an API that is not supported by one of your licenses. • If using one of our SDKs, don't assume that the license value listed in the Github example code is the right one. • Don't try to use an ability that doesn't pertain to your specific license. Examples: • When calling our US Street Address API, you include match=enhanced, but you don't have a US Core Edition license. You only have the older US Standard Edition license (which doesn’t include enhanced matching). • When calling our International Street API, you include geocode=true, but your license is an International Global Basic license that doesn't include geocodes.
Common Mistakes That Result in a Payment Required Error • Don't use API keys from the wrong account. • Don't try to call an API that is not supported by one of your licenses. • If using one of our SDKs, don't assume that the license value listed in the Github example code is the right one. • Don't try to use an ability that doesn't pertain to your specific license. Examples: • When calling our US Street Address API, you include match=enhanced, but you don't have a US Core Edition license. You only have the older US Standard Edition license (which doesn’t include enhanced matching). • When calling our International Street API, you include geocode=true, but your license is an International Global Basic license that doesn't include geocodes. • When calling our International Street API, you submit an address from a country not included with your particular license.
Finishing Up The Smarty Support team is here for you. We pride ourselves on being super responsive. Our regular hours are weekdays 8 to 5 Mountain Time. Phone: 801-877-5778 Chat: smarty.com Email: support@smarty.com
Try our APIs for free! smarty.com/signup