{"_id":"57624356653c2d2200fec7d6","project":"55c8cff571d7580d0063a5e5","user":"55c8cf9471d7580d0063a5e4","category":{"_id":"57624356653c2d2200fec79d","project":"55c8cff571d7580d0063a5e5","__v":0,"version":"57624356653c2d2200fec79c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-10T16:23:18.580Z","from_sync":false,"order":0,"slug":"documentation","title":"Getting Started"},"githubsync":"","__v":7,"parentDoc":null,"version":{"_id":"57624356653c2d2200fec79c","__v":22,"project":"55c8cff571d7580d0063a5e5","createdAt":"2016-06-16T06:12:38.244Z","releaseDate":"2016-06-16T06:12:38.244Z","categories":["57624356653c2d2200fec79d","57624356653c2d2200fec79e","57624356653c2d2200fec79f","57624356653c2d2200fec7a0","57624356653c2d2200fec7a1","57624356653c2d2200fec7a2","57624356653c2d2200fec7a3","57624356653c2d2200fec7a4","57624356653c2d2200fec7a5","57624356653c2d2200fec7a6","57624356653c2d2200fec7a7","57624356653c2d2200fec7a8","57624356653c2d2200fec7a9","57624356653c2d2200fec7aa","5779ca1b99b40b0e005abb3a","5779d198aea88b0e00f63277","5797d3ab17ced017003c4be4","57ac170ef1cdae0e0053cdfc","57dbfc723ed3450e00dc9e6d","5804d12d16161c0f0077df9b","5841064b652e5b0f0015a7c8","588b5e5f2966b2230009cbf9","58a68ebf3239fa0f00857619","58c23c8b4922930f0050ac91","58fd1460809fc30f00f2ee07","5934eaf5328680002d77de6a","594bf91601cfe6000f40f4c5","595c4ed696b447001ba0cf6d","596524495cee50001575f5be","5970d4f1313162004dd303b5","59780fac24dbd1001a1fa057","59a8cfd3ead78a002d63cafe","59e0323d93da1f001c9ec170","5b0c16f2be9fcb0003e28222","5ba8fd1a4c8c220003a08f0f"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"4.0.0","version":"4"},"updates":["57928be169c5120e00efdeed","5792931390ad641700d46bbe"],"next":{"pages":[],"description":""},"createdAt":"2016-03-14T16:17:30.298Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"We designed this API as a JSON-based REST API to make integration easy.  For a very basic test, try loading our base URL, [https://api.phone.com/v4](https://api.phone.com/v4), in your web browser.\n\nPart of being a REST API is including links and other metadata in our response bodies.  This means our API is partially _self-documenting_.  By default, our response bodies include whitespace to make them more human-readable.  We also feature judicious use of metadata and context-sensitive links to inform you about related resources.  We format these using the [Mason, draft 2](https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md) specification.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Which API again?\",\n  \"body\": \"Note that this website refers to our new API, codenamed \\\"Phoenix\\\", which we launched in the Spring of 2016.  If you were a Phone.com customer prior to this, you might be looking for our earlier [XML API](https://www.phone.com/api) or maybe our [V1 \\\"REST\\\" API](http://docs.phone.com).  Confusing? Yeah, we know.  Both of these will eventually be retired as we finish adding the same functionalities here. Don't worry, though. We'll notify you well in advance of taking them offline.\"\n}\n[/block]\n## Intro to Mason\n\nMason is a JSON-based REST media type.  It's like [HAL](http://stateless.co/hal_specification.html), but with several key enhancements. For starters, all Mason properties are prefixed with the `:::at:::` symbol.  Here is an example of a basic Mason response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"@meta\\\": {\\n        \\\"@title\\\": \\\"Basic info on Cookie Monster\\\"\\n    },\\n    \\\"first_name\\\": \\\"Cookie\\\",\\n    \\\"last_name\\\": \\\"Monster\\\",\\n    \\\"texture\\\": \\\"furry\\\",\\n    \\\"color\\\": \\\"blue\\\",\\n    \\\"@controls\\\": {\\n        \\\"self\\\": {\\n            \\\"href\\\": \\\"https://api.phone.com/sesame-st/characters/cookie\\\"\\n        },\\n        \\\"phx:list-friends\\\": {\\n            \\\"href\\\": \\\"https://api.phone.com/sesame-st/characters/cookie/friends\\\",\\n        },\\n        \\\"up\\\": {\\n            \\\"href\\\": \\\"https://api.phone.com/sesame-st/characters\\\"\\n        }\\n    },\\n    \\\"@namespaces\\\": {\\n        \\\"phx\\\": {\\n            \\\"name\\\": \\\"https://apidocs.phone.com/docs/\\\"\\n        }\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nTo obtain all of the data properties without any Mason properties, you can ignore or remove any property whose name begins with `@`.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Mason Properties Omitted\",\n  \"body\": \"In order to emphasize the data that our API returns, most of the examples throughout this website omit any Mason properties.\"\n}\n[/block]\nThere are 4 main Mason properties you will see in our API responses.  They are described below. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"@controls\"\n}\n[/block]\nThe `@controls` property is by far the most important one. It has a list of any links and/or forms that are related to the object you are looking at.  `@controls` can appear at any level in the response body.  If it appears in the root level, it describes the body as a whole.  If it appears deeper in the structure, it describes the object it is attached to.\n\n`@controls` is a dictionary structure.  The keys are link relations. The values are objects that describe the link or the form.  Individual control objects always have an `href` property, which is the URL pointing to the item.  There are several additional properties that reveal how the URL is to be accessed.  Common properties include the following:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Data Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`href`\",\n    \"0-1\": \"URL\",\n    \"0-2\": \"The URL that the control points to\",\n    \"1-0\": \"`method`\",\n    \"1-1\": \"HTTP Verb\",\n    \"1-2\": \"Method used for accessing the URL (default is GET)\",\n    \"2-0\": \"`schemaUrl`\",\n    \"2-1\": \"URL\",\n    \"2-2\": \"JSON Schema document describing the inputs this URL accepts\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"@controls\\\": {\\n    \\\"up\\\": {\\n        \\\"href\\\": \\\"https://api.phone.com\\\",\\n        \\\"title\\\": \\\"Phone.com API\\\"\\n    },\\n    \\\"self\\\": {\\n        \\\"href\\\": \\\"https://api.phone.com/accounts\\\",\\n    },\\n    \\\"pc:account-list-post\\\": {\\n        \\\"href\\\": \\\"https://api.phone.com/accounts\\\",\\n        \\\"method\\\": \\\"POST\\\",\\n        \\\"schemaUrl\\\": \\\"https://api.phone.com/inputs/phx/create-account\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"@namespaces\"\n}\n[/block]\nThe `@namespaces` object is related to the `@controls` object.  It provides a shorthand for locating the documentation for the custom link relations we use (e.g. `phx:list-friends`.)  It's a dictionary structure where each key is a namespace (e.g. \"phx\" for our local Phone.com namespace), and the value is an object describing it.  You will see a `name` field inside this object, where the value is a URL.  To obtain the documentation URL for a custom link relation, remove the namespace from the link relation, and add the remaining portion to the end of the URL you see.  To continue our example, the documentation for the `phx:list-friends` relation would be located at `https://apidocs.phone.com/docs/list-friends`.\n\nHere is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"@namespaces\\\": {\\n    \\\"phx\\\": {\\n        \\\"name\\\": \\\"https://apidocs.phone.com/docs/\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"@meta\"\n}\n[/block]\nThe `@meta` object only appears in the root level of a Mason document. It has any number of metadata properties. Here is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"@meta\\\": {\\n    \\\"@title\\\": \\\"Create a new account\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Humans only\",\n  \"body\": \"The `@meta` property and its contents are meant for humans only.  When a client uses Mason's `Prefer: representation=minimal` header, `@meta` is omitted, among other things.  DO NOT programmatically access anything inside `@meta`, since it might not be present at runtime.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"@error\"\n}\n[/block]\nThe `@error` object communicates details about API errors.  Here are some examples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"@error\\\": {\\n    \\\"@message\\\": \\\"Unprocessable Entity\\\",\\n    \\\"@httpStatusCode\\\": 422,\\n    \\\"fields\\\": {\\n        \\\"filter\\\": [\\n            \\\"Unsupported query argument\\\"\\n        ]\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"@error\\\": {\\n    \\\"@message\\\": \\\"Unauthorized\\\",\\n    \\\"@httpStatusCode\\\": 401,\\n    \\\"@code\\\": \\\"oauth2.access_denied\\\",\\n    \\\"@details\\\": \\\"OAuth error: Access token was not found or has expired\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"introduction","type":"basic","title":"Introduction"}
We designed this API as a JSON-based REST API to make integration easy. For a very basic test, try loading our base URL, [https://api.phone.com/v4](https://api.phone.com/v4), in your web browser. Part of being a REST API is including links and other metadata in our response bodies. This means our API is partially _self-documenting_. By default, our response bodies include whitespace to make them more human-readable. We also feature judicious use of metadata and context-sensitive links to inform you about related resources. We format these using the [Mason, draft 2](https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md) specification. [block:callout] { "type": "info", "title": "Which API again?", "body": "Note that this website refers to our new API, codenamed \"Phoenix\", which we launched in the Spring of 2016. If you were a Phone.com customer prior to this, you might be looking for our earlier [XML API](https://www.phone.com/api) or maybe our [V1 \"REST\" API](http://docs.phone.com). Confusing? Yeah, we know. Both of these will eventually be retired as we finish adding the same functionalities here. Don't worry, though. We'll notify you well in advance of taking them offline." } [/block] ## Intro to Mason Mason is a JSON-based REST media type. It's like [HAL](http://stateless.co/hal_specification.html), but with several key enhancements. For starters, all Mason properties are prefixed with the `@` symbol. Here is an example of a basic Mason response: [block:code] { "codes": [ { "code": "{\n \"@meta\": {\n \"@title\": \"Basic info on Cookie Monster\"\n },\n \"first_name\": \"Cookie\",\n \"last_name\": \"Monster\",\n \"texture\": \"furry\",\n \"color\": \"blue\",\n \"@controls\": {\n \"self\": {\n \"href\": \"https://api.phone.com/sesame-st/characters/cookie\"\n },\n \"phx:list-friends\": {\n \"href\": \"https://api.phone.com/sesame-st/characters/cookie/friends\",\n },\n \"up\": {\n \"href\": \"https://api.phone.com/sesame-st/characters\"\n }\n },\n \"@namespaces\": {\n \"phx\": {\n \"name\": \"https://apidocs.phone.com/docs/\"\n }\n }\n}", "language": "json" } ] } [/block] To obtain all of the data properties without any Mason properties, you can ignore or remove any property whose name begins with `@`. [block:callout] { "type": "info", "title": "Mason Properties Omitted", "body": "In order to emphasize the data that our API returns, most of the examples throughout this website omit any Mason properties." } [/block] There are 4 main Mason properties you will see in our API responses. They are described below. [block:api-header] { "type": "basic", "title": "@controls" } [/block] The `@controls` property is by far the most important one. It has a list of any links and/or forms that are related to the object you are looking at. `@controls` can appear at any level in the response body. If it appears in the root level, it describes the body as a whole. If it appears deeper in the structure, it describes the object it is attached to. `@controls` is a dictionary structure. The keys are link relations. The values are objects that describe the link or the form. Individual control objects always have an `href` property, which is the URL pointing to the item. There are several additional properties that reveal how the URL is to be accessed. Common properties include the following: [block:parameters] { "data": { "h-0": "Property", "h-1": "Data Type", "h-2": "Description", "0-0": "`href`", "0-1": "URL", "0-2": "The URL that the control points to", "1-0": "`method`", "1-1": "HTTP Verb", "1-2": "Method used for accessing the URL (default is GET)", "2-0": "`schemaUrl`", "2-1": "URL", "2-2": "JSON Schema document describing the inputs this URL accepts" }, "cols": 3, "rows": 3 } [/block] Here is an example: [block:code] { "codes": [ { "code": "\"@controls\": {\n \"up\": {\n \"href\": \"https://api.phone.com\",\n \"title\": \"Phone.com API\"\n },\n \"self\": {\n \"href\": \"https://api.phone.com/accounts\",\n },\n \"pc:account-list-post\": {\n \"href\": \"https://api.phone.com/accounts\",\n \"method\": \"POST\",\n \"schemaUrl\": \"https://api.phone.com/inputs/phx/create-account\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "@namespaces" } [/block] The `@namespaces` object is related to the `@controls` object. It provides a shorthand for locating the documentation for the custom link relations we use (e.g. `phx:list-friends`.) It's a dictionary structure where each key is a namespace (e.g. "phx" for our local Phone.com namespace), and the value is an object describing it. You will see a `name` field inside this object, where the value is a URL. To obtain the documentation URL for a custom link relation, remove the namespace from the link relation, and add the remaining portion to the end of the URL you see. To continue our example, the documentation for the `phx:list-friends` relation would be located at `https://apidocs.phone.com/docs/list-friends`. Here is an example: [block:code] { "codes": [ { "code": "\"@namespaces\": {\n \"phx\": {\n \"name\": \"https://apidocs.phone.com/docs/\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "@meta" } [/block] The `@meta` object only appears in the root level of a Mason document. It has any number of metadata properties. Here is an example: [block:code] { "codes": [ { "code": "\"@meta\": {\n \"@title\": \"Create a new account\"\n}", "language": "json" } ] } [/block] [block:callout] { "type": "warning", "title": "Humans only", "body": "The `@meta` property and its contents are meant for humans only. When a client uses Mason's `Prefer: representation=minimal` header, `@meta` is omitted, among other things. DO NOT programmatically access anything inside `@meta`, since it might not be present at runtime." } [/block] [block:api-header] { "type": "basic", "title": "@error" } [/block] The `@error` object communicates details about API errors. Here are some examples: [block:code] { "codes": [ { "code": "\"@error\": {\n \"@message\": \"Unprocessable Entity\",\n \"@httpStatusCode\": 422,\n \"fields\": {\n \"filter\": [\n \"Unsupported query argument\"\n ]\n }\n}", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "\"@error\": {\n \"@message\": \"Unauthorized\",\n \"@httpStatusCode\": 401,\n \"@code\": \"oauth2.access_denied\",\n \"@details\": \"OAuth error: Access token was not found or has expired\"\n}", "language": "json" } ] } [/block]