diff --git a/all/all-apis/domainsearch.service.json b/all/all-apis/domainsearch.service.json new file mode 100644 index 0000000000..52192148d6 --- /dev/null +++ b/all/all-apis/domainsearch.service.json @@ -0,0 +1,290 @@ +{ + "name": "DomainSearch", + "client_id": "https://github.com/wix-private/premium/tree/master/domains/domain-search#public", + "memberOf": "All APIs", + "category": "core", + "mixes": [], + "labels": [], + "docs": { + "summary": "Check domain availabilities and get suggestions", + "description": [] + }, + "properties": [], + "tags": [ { + "name": "DomainSearch", + "entity": null + }], + "relatedGuides": [ + { + "path": "../guides/domainsearch/docs/UseCases.md", + "name": "Sample Flow" + }, + { + "path": "../guides/domainsearch/docs/ErrorMessages.md", + "name": "Error Messages" + }, + { + "path": "../guides/domainsearch/docs/PublicIntro.md", + "name": "Introduction" + }, + { + "path": "../guides/domainsearch/docs/Intro.md", + "name": "Internal Introduction" + } + ], + "operations": [ + { + "name": "Check Domain Availability", + "methodName": "CheckDomainAvailability", + "serviceName": "DomainAvailabilityService", + "tag": "DomainSearch", + "permissions": [], + "events": [], + "labels": [], + "nameParams": [], + "requiredFields": ["domain"], + "params": [ { + "in": "QUERY", + "name": "domain", + "type": "string", + "doc": "\nDomain name. Must include the TLD. For example, `my-new-domain.com`.\n", + "required": true + }], + "ret": { + "type": { + "name": "CheckDomainAvailability", + "statusCode": "200", + "typeParams": ["All APIs.DomainSearch._com_wixpress_premium_domain_search_availability_v2_CheckDomainAvailabilityResponse"] + }, + "doc": "" + }, + "locations": [], + "docs": { + "summary": "\nChecks whether the given domain is available for purchase.\n\n\nThe `domain` field must include the TLD. For example, `my-new-domain.com`.\n \n", + "description": [], + "request": "GET", + "url": "https://www.wixapis.com/domain-search/v2/check-domain-availability", + "links": [], + "examples": [ { + "title": "Checks whether a specific domain is available for purchase at Wix.", + "body": ["curl -X GET \n'https://www.wixapis.com/domain-search/v2/check-domain-availability?domain=mydomain.com' \\\n-H 'Authorization: ' \\"], + "response": ["{\"availability\": {\n \"domain\": \"mydomain.com\",\n \"available\": false\n}} "], + "type": "curl", + "extra": {} + }], + "extra": {} + }, + "extra": { + "hasRest": true, + "rpcRequestName": "CheckDomainAvailabilityRequest", + "rpcResponseName": "CheckDomainAvailabilityResponse" + }, + "customLabels": [{"id": "maturity-beta"}] + }, + { + "name": "Suggest Domains", + "methodName": "SuggestDomains", + "serviceName": "DomainSearchService", + "tag": "DomainSearch", + "permissions": [], + "events": [], + "labels": [], + "nameParams": [], + "requiredFields": ["query"], + "params": [ + { + "in": "QUERY", + "name": "query", + "type": "string", + "doc": "\nInput to base your domain suggestions on. May include \nletters, numbers, spaces, dots, and hyphens. Must not include the TLD.\n\nMin: 3 characters \nMax: 100 characters\n", + "required": true + }, + { + "in": "QUERY", + "name": "tlds", + "type": { + "name": "array", + "typeParams": ["string"] + }, + "doc": "\n[Top-level domains](https://en.wikipedia.org/wiki/Top-level_domain). Must \nnot include the dot. For example, `com`, not `.com`. Not all TLDs can be \nconnected to Wix sites. Supported TLDS include `com`, `net`, and `org`. \nContact the [Wix B2B sales team](mailto:bizdev@wix.com) for more \ninformation.\n\nMax: 10 TLDs\n", + "required": false + }, + { + "in": "QUERY", + "name": "limit", + "type": "integer", + "doc": "\nNumber of domain suggestions to be returned. \n\nMin: `1` \nMax: `20` \nDefault: `5`\n", + "required": false + } + ], + "ret": { + "type": { + "name": "SuggestDomains", + "statusCode": "200", + "typeParams": ["All APIs.DomainSearch._com_wixpress_premium_domain_search_suggest_v2_SuggestDomainsResponse"] + }, + "doc": "" + }, + "locations": [], + "docs": { + "summary": "\nSuggests domains available for purchase, based on the provided query input.\n\nThe `tlds` must not include the dot. For example, `com` and not `.com`.\n \n", + "description": [], + "request": "GET", + "url": "https://www.wixapis.com/domain-search/v2/suggest-domains", + "links": [], + "examples": [ { + "title": "Suggests available domains available for purchase.", + "body": ["\ncurl -X GET \n'https://www.wixapis.com/domain-search/v2/suggest-domains?query=my%20stunning%20domain&limit=4&tlds=com&tlds=love' \\\n-H 'Authorization: ' \\"], + "response": ["{\"suggestions\": [\n {\"domain\": \"find-my-domain.com\"},\n {\"domain\": \"mydomain.com\"},\n {\"domain\": \"mydomain.love\"},\n {\"domain\": \"my-domain.love\"}\n]} "], + "type": "curl", + "extra": {} + }], + "extra": {} + }, + "extra": { + "hasRest": true, + "rpcRequestName": "SuggestDomainsRequest", + "rpcResponseName": "SuggestDomainsResponse" + }, + "customLabels": [{"id": "maturity-beta"}] + } + ], + "events": [], + "callbacks": [], + "messages": [ + { + "name": "_com_wixpress_premium_domain_search_availability_v2_CheckDomainAvailabilityRequest", + "displayName": "Check Domain Availability Request Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ { + "name": "domain", + "type": "string", + "doc": "\nDomain name. Must include the TLD. For example, `my-new-domain.com`.\n" + }], + "enum": null, + "extra": {}, + "labels": [] + }, + { + "name": "_com_wixpress_premium_domain_search_availability_v2_CheckDomainAvailabilityResponse", + "displayName": "Check Domain Availability Response Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ { + "name": "availability", + "type": "All APIs.DomainSearch._com_wixpress_premium_domain_search_availability_v2_DomainAvailability", + "doc": " \nInformation about the domain's availability.\n" + }], + "enum": null, + "extra": {}, + "labels": [] + }, + { + "name": "_com_wixpress_premium_domain_search_availability_v2_DomainAvailability", + "displayName": "Domain Availability Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ + { + "name": "domain", + "type": "string", + "doc": "\nDomain name including TLD. For example, `my-new-domain.com`.\n" + }, + { + "name": "available", + "type": "boolean", + "doc": " \nWhether the domain is available for purchase.\n" + } + ], + "enum": null, + "extra": {}, + "labels": [] + }, + { + "name": "_com_wixpress_premium_domain_search_suggest_v2_SuggestDomainsRequest", + "displayName": "Suggest Domains Request Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ + { + "name": "query", + "type": "string", + "doc": "\nInput to base your domain suggestions on. May include \nletters, numbers, spaces, dots, and hyphens. Must not include the TLD.\n\nMin: 3 characters \nMax: 100 characters\n" + }, + { + "name": "tlds", + "type": { + "name": "array", + "typeParams": ["string"] + }, + "doc": "\n[Top-level domains](https://en.wikipedia.org/wiki/Top-level_domain). Must \nnot include the dot. For example, `com`, not `.com`. Not all TLDs can be \nconnected to Wix sites. Supported TLDS include `com`, `net`, and `org`. \nContact the [Wix B2B sales team](mailto:bizdev@wix.com) for more \ninformation.\n\nMax: 10 TLDs\n" + }, + { + "name": "limit", + "type": "integer", + "doc": "\nNumber of domain suggestions to be returned. \n\nMin: `1` \nMax: `20` \nDefault: `5`\n" + } + ], + "enum": null, + "extra": {}, + "labels": [] + }, + { + "name": "_com_wixpress_premium_domain_search_suggest_v2_SuggestDomainsResponse", + "displayName": "Suggest Domains Response Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ { + "name": "suggestions", + "type": { + "name": "array", + "typeParams": ["All APIs.DomainSearch._com_wixpress_premium_domain_search_suggest_v2_DomainSuggestion"] + }, + "doc": " List of suggested domains.\n" + }], + "enum": null, + "extra": {}, + "labels": [] + }, + { + "name": "_com_wixpress_premium_domain_search_suggest_v2_DomainSuggestion", + "displayName": "Domain Suggestion Object", + "locations": [], + "docs": { + "summary": "", + "links": [], + "examples": [] + }, + "members": [ { + "name": "domain", + "type": "string", + "doc": " Suggested domain name including TLD.\n" + }], + "enum": null, + "extra": {}, + "labels": [] + } + ], + "extra": {"artifactId": "com.wixpress.premium.domains.domain-search"} +} \ No newline at end of file diff --git a/all/guides/domainsearch/docs/ErrorMessages.md b/all/guides/domainsearch/docs/ErrorMessages.md new file mode 100644 index 0000000000..21c56b624e --- /dev/null +++ b/all/guides/domainsearch/docs/ErrorMessages.md @@ -0,0 +1,26 @@ +# Domain Search Errors + + +This article outlines error messages that might be issued when calling endpoints of the Domain Search API. + + +## Check Domain Availability Errors + + +The [Check Domain Availability](https://dev.wix.com/api/rest/account-level-apis/domain-search/check-domain-availibility) endpoint might issue the following error message: + +|
HTTP status
|
Error code
|
Error message
|
Troubleshooting
| +| --------------------------- | ----------------------------------- | ------------------------------------------------------------ | ------------------------------ | +| `INVALID_ARGUMENT (400)` | `INVALID_DOMAIN` | Failed to extract root domain from ``, or TLD is missing or invalid. | Start a new query including a domain name and supported TLD. Domain name and TLD must be separated by a dot. For example, `my-new-domain.com`. | + + +## Suggest Domains Errors + + +The [Suggest Domains](https://dev.wix.com/api/rest/account-level-apis/domain-search/suggest-domains) endpoint might issue the following error messages: + +|
HTTP status
|
Error code
|
Error message
|
Troubleshooting
| +| --------------------------- | ----------------------------------- | ------------------------------------------------------------ | ------------------------------ | +| `INVALID_ARGUMENT (400)` | `INVALID_QUERY` | Query `` has invalid characters. Only alphanumeric values, hyphens, dots, and spaces are supported. | Start a new query using only alphanumeric values, hyphens, dots, and spaces. | +| `INVALID_ARGUMENT (400)` | `INVALID_TLD_FORMAT` | At least one element of the `tlds` array has an invalid format. | Start a new query using the correct TLD format. TLDs must not include the dot. For example, `com`, not `.com`. | +| `INVALID_ARGUMENT (400)` | `TLD_NOT_SUPPORTED` | Unsupported TLDs `` found. | Start a new query with supported TLDs such as `com`, `net`, and `org`. Contact the [Wix B2B sales team](bizdev@wix.com) for more information. | diff --git a/all/guides/domainsearch/docs/Intro.md b/all/guides/domainsearch/docs/Intro.md new file mode 100644 index 0000000000..60718a64d2 --- /dev/null +++ b/all/guides/domainsearch/docs/Intro.md @@ -0,0 +1,43 @@ +# About the API + + +The Domain Search API allow you to: + +- check a domain availability. +- suggest domains. + + +## High level Diagram + +![alt text](./assets/domain-search.png) + +## Terminology + +### Domain + +- **Availability** +
+- A domain that has already been taken has availability equal to false. +- A domain that is still available for purchase has availability equal to true. + +- **Suggestion** +
+- A domain that is available for purchase at Wix. + + +## Error Handling + +The api will throw errors if something goes wrong. + +User input validation for the check availability API: + +- domain - required field. +- domain - must be in a hostname domain format. + +User input validation of the suggest API: + +- query - required field, can be any alphanumeric text with spaces and hyphens +- tlds - a list of tlds, i.e. ["com", "net", "org"] +- limit - optional number, can be between 1 and 20 + +Business error thrown by the API: diff --git a/all/guides/domainsearch/docs/PublicIntro.md b/all/guides/domainsearch/docs/PublicIntro.md new file mode 100644 index 0000000000..059ea9569e --- /dev/null +++ b/all/guides/domainsearch/docs/PublicIntro.md @@ -0,0 +1,35 @@ +# About the Domain Search API + + +With the Domain Search API you can help site owners find fitting domains for +their sites or check the availability of a specific domain. The API allows +you to: + +- Check whether a specific domain is available for purchase. +- Generate suggestions for available domains. + + +If you've already bought a domain, you can use the +[Connect Domain API](https://dev.wix.com/api/rest/account-level-apis/domain-search/connect-domain) +to connect it to a Wix site. + + +## Terminology + + ++ __Domain__: Domain name including TLD. ++ __TLD__: [Top-level domain](https://en.wikipedia.org/wiki/Top-level_domain). + For example, `com`, `net`, or `org`. ++ __Suggestion__: A suggested domain that's available for purchase. + + +## Before you begin + + ++ Not all TLDs can be connected to Wix sites. Contact the Wix B2B sales team at + bizdev@wix.com for more information. ++ Currently, you can't use Wix APIs to buy domains. But you can use the + [Connect Domain API](https://dev.wix.com/api/rest/account-level-apis/domains/connect-domain) + to connect an already delivered domain to a Wix site. + + diff --git a/all/guides/domainsearch/docs/UseCases.md b/all/guides/domainsearch/docs/UseCases.md new file mode 100644 index 0000000000..b7c4697236 --- /dev/null +++ b/all/guides/domainsearch/docs/UseCases.md @@ -0,0 +1,27 @@ +# Sample Use Case & Flow: Domain Search + + +This article shares a possible use case your app could support, as well as an example flow. +You're certainly not limited to this use case, but it can be a helpful jumping off point +as you plan your app's implementation. + + +## Help site owners set up their domain + + +Your app could help site owners identify their favorite available domain name. +Then, you could purchase the corresponding domain for them and connect it to +their site. + + +1. Call the [Suggest Domains endpoint](https://dev.wix.com/api/rest/account-level-apis/domain-search/suggest-domains). +1. Display the suggestions to the site owners and let them select their preferred choice. +1. Purchase the domain through an external provider. +1. Identify the relevant site through the + [Query Sites endpoint](https://dev.wix.com/api/rest/account-level-apis/sites/query-sites). +1. Use the + [Create Package endpoint of the Resellers API](https://dev.wix.com/api/rest/account-level-apis/resellers/packages/create-package-v2) + to offer the domain to the site owners. +1. Call the + [Connect Domain endpoint](https://dev.wix.com/api/rest/account-level-apis/domain-search/connect-domain) + to connect the domain to the relevant site.