@@ -7,10 +7,114 @@ show_sidebar: true
77Extensions enable an API to provide clients with information or functionality
88beyond that described in the base JSON API specification.
99
10+ Anyone can author an extension, and a single extension can be reused by
11+ multiple APIs. Popular extensions may be implemented by off-the-shelf tools
12+ so that developers can seamlessly take advantage of the features these
13+ extensions provide.
14+
1015## <a href =" #existing-extensions " id =" existing-extensions " class =" headerlink " ></a > Existing Extensions
1116
1217Patience, my friend. A list of existing extensions is coming very soon.
1318
19+ ## <a href =" #extension-registration " id =" extension-registration " class =" headerlink " ></a > Registering a New Extension
20+
21+ ### <a href =" #extension-registration-before " id =" extension-registration-before " class =" headerlink " ></a > Before You Register
22+
23+ Please ** check whether existing extension fits your needs or could be amended
24+ to fit your needs** before registering a new extension.
25+
26+ - If a suitable extension already exists, consider using it. Having fewer, more
27+ widely-deployed extensions makes it easier to develop common tools.
28+
29+ - If there's an existing extension that could be amented to fit your needs,
30+ consider asking the extension's author if they would be willing to modify it as
31+ needed. Contact them through the information in their extension's registration
32+ and give them a week or two to reply.
33+
34+ ### <a href =" #extension-registration-template " id =" extension-registration-template " class =" headerlink " ></a > Registration Template
35+
36+ If you do decide to create a new extension, you must register it. Your extension
37+ will be ** approved within a week** by one of JSON API's editors, assuming it
38+ meets the [ profile extension requirements] ( /format/1.1/#extending-profile-extensions-characteristics ) .
39+
40+ To submit a registration request, simply copy the markdown template below, fill
41+ it out, and post the result as an issue on our [ GitHub] ( https://github.com/json-api/json-api )
42+ or a new thread on our [ discussion forum] ( http://discuss.jsonapi.org/ ) .
43+
44+ > \# [ Your Extension Name Here]
45+ >
46+ > Add a description here (no more than a paragraph) about your extension's
47+ > purpose and features to help other users determine if it will work for them.
48+ >
49+ > \# (Optional) Minimum JSON API Version
50+ >
51+ > If your extension only works with certain versions of JSON API, you may note
52+ > that here. Such a restriction would be appropriate if the values your
53+ > extension defines can only be used in objects that were not present
54+ > before a certain JSON API version.
55+ >
56+ > \# Specification
57+ >
58+ > In this section, describe the values that can occur as your extension's data,
59+ > and the places where those values are allowed. This description should be
60+ > detailed enough to allow for interoperable implementations, but it otherwise
61+ > doesn't need to be formal.
62+ >
63+ > For reference, your extension may define values for use at the root level of:
64+ >
65+ > - the [ document] ( /format/#document-top-level )
66+ > - a [ resource object] ( /format/#document-resource-objects ) (i.e., as a sibling of the ` type ` and ` id ` keys)
67+ > - a [ relationship object] ( /format/#document-resource-object-relationships-relationship-object )
68+ > - a [ link object] ( /format/#document-links-link-object ) (i.e., as a sibling of ` href ` )
69+ > - a [ resource identifier object] ( /format/#document-resource-identifier-objects )
70+ > - an [ error object] ( /format/#error-objects )
71+ >
72+ > Make sure your extension's specification follows the
73+ > [ profile extension requirements] ( /format/1.1/#extending-profile-extensions-characteristics )
74+ > listed in the main specification, especially those on key naming and what an
75+ > extension is not allowed to do.
76+ >
77+ > Finally, it is ** strongly encouraged** that your extension:
78+ >
79+ > - Reuse objects, patterns, and key names from the main JSON API specification
80+ > where appropriate. For instance, if your extension defines a field that
81+ > points to another JSON API resource, that field should hold a resource
82+ > identifier object. Or, if your extension defines a "type" key, it should use
83+ > that key as JSON API does (i.e. to hold a string indicating a resource's type).
84+ >
85+ > - Include a rule that tells recipients how to handle data from your extension
86+ > that they don't understand. This will enable your extension to be added to
87+ > over time without breaking message recipients designed for the extension's
88+ > older format. ([ Learn more.] ( http://davidbau.com/archives/2003/12/01/theory_of_compatibility_part_1.html ) )
89+ > For this rule, JSON API recommends the text:
90+ >
91+ > <i>Recipients of a document containing this extension MUST ignore members
92+ > in this extension's data that they do not recognize.</i>
93+ >
94+ > \# Registrant Contact Information
95+ >
96+ > \- Name: <br />
97+ > \- Email: <br />
98+ > \- Website (Optional): <br />
99+ > \- Phone (Optional):
100+
101+ ### <a href =" #extension-registration-other " id =" extension-registration-other " class =" headerlink " ></a > Other Information
102+
103+ The community may give you feedback on your registration request before it's
104+ approved, but you are not required to act on this feedback; your extension _ will_
105+ be approved if it meets the requirements.
106+
107+ One caveat about the process and timeline outlined above: if your extension
108+ defines a new, fundamental mechanism for doing something "architectural" that
109+ other extensions may need to do too, it may be held for extra consideration.
110+ This extra review is designed to check that the proposed mechanism, were it to
111+ become a convention, wouldn't have problematic ramifications.
112+
113+ Finally, if the author of an extension has died, moved out of contact, or
114+ otherwise can't or won't make changes that are important to the community, the
115+ JSON API editors may reassign responsibility for the extension, to allow it to
116+ continue to evolve.
117+
14118## <a href =" #deprecated-extensions " id =" deprecated-extensions " class =" headerlink " ></a > Deprecated Extensions
15119
16120JSON API previously offered experimental support for a different extension
0 commit comments