forked from CDLUC3/ezid-info-pages
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsuffix_passthrough.html
113 lines (84 loc) · 8 KB
/
suffix_passthrough.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
{% extends "layouts/learn.html" %}
{% load layout_extras %}
{% load menus %}
{% load i18n %}
{% block title %}{% block title-twitter %}{% trans "Suffix Passthrough Explained" %}{% endblock %}{% endblock %}
{% block heading %}{% content_heading _("Suffix Passthrough Explained") %}{% endblock %}
{% block content %}
{% comment %}Don't need to translate this{% endcomment %}
{% learn_breadcrumb _("Suffix Passthrough Explained") _("Documentation") "#04" %}
<div class="container api">
{% comment %}Translators: Copy HTML tags over and only translate words outside of these tags
i.e.: <p>TRANSLATE TEXT WRAPPED BY HTML TAGS</p>
i.e.: <a href="don't_translate_urls">PLEASE PRESERVE HTML TAGS</a>
{% endcomment %}
{% blocktrans trimmed %}
<h2 class="heading_2">What is Suffix Passthrough?</h2>
<p class="diagram__img-wrapper"><img class="diagram__img" alt="Illustration of suffix passing from the end of a submitted ARK to the end of a registered target URL." src="/static/info/learn_spt_in_action.gif"/></p>
<p><span style="white-space:nowrap">Suffix Passthrough (SPT)</span> is a feature that lets you add any suffix to an identifier, and when a user selects ("clicks on") the identifier, the suffix is added to the end of the identifier's location (target) URL. It dramatically reduces the maintenance burden by permitting one identifier to stand in for many identifiers.</p>
<p>The transformation of an identifier into its final location URL is done by a web server called a <em>resolver</em>, and the transformation is called <em>resolution</em>. Typically a web browser uses the resolver to find the final location URL, which it then displays in its location bar. Currently SPT works only for ARK identifiers and only with the <a href="http://n2t.net/" class="ext-link" rel="nofollow"><span style="color: blue;">Name-to-Thing (N2T)</span></a> resolver. </p>
<p>Basically, Suffix Passthrough makes every ARK the root of its own "namespace". Any user-added suffix, which is a common way to form sub-object identifiers, will be passed through to the registered target object. For example, a dataset with 10,000 component parts and just this one "ancestor" ARK,</p>
<div class="pre-block">
<code>http://n2t.net/ark:/12345/x98765</code><br/>
</div>
<p>would effectively allow access to 10,000 ARKs, but only require you to manage the ancestor ARK. Those sub-object ARKs might look like:</p>
<div class="pre-block">
<code>http://n2t.net/ark:/12345/x98765/study1/location1/day1.cs</code><br/>
<code>http://n2t.net/ark:/12345/x98765/study1/location3/day19.cs</code><br/>
<code> ...</code><br/>
<code>http://n2t.net/ark:/12345/x98765/study92/location18/day96.xlsx</code><br/>
</div>
<p>When a user clicks on one, it is submitted to N2T. Failing to find it registered, N2T scans backwards starting from the end of the user-supplied ARK string and stops at the first ancestor ARK that is registered.</p>
<p>The part that was scanned over, stretching from the first registered ancestor ARK to the end of the original string, comprises the suffix.</p>
<div class="pre-block">
<code>http://n2t.net/ark:/12345/x98765<span style="color: red;">/study92/location18/day96.xlsx</span></code><br/>
<code>\______________________________<em>/\</em>____________________________/</code><br/>
<code> ancestor ARK <span style="color: red;">suffix</span></code><br/>
</div>
<p>Then it redirects the user's browser to the ancestor's target URL, appending the suffix that it scanned. So if the ancestor ARK's target was,</p>
<div class="pre-block">
<code>http://n2t.net/ark:/12345/x98765 --> <span style="color: blue;">http://datazoo.example.com/carbon288</span></code><br/>
<code>\______________________________<em>/ \_</em>_________________________________/</code><br/>
<code> ancestor ARK <span style="color: blue;">ancestor ARK's target URL</span></code><br/>
</div>
<p>the user would be (hypothetically) redirected to</p>
<div class="pre-block">
<code><span style="color: blue;">http://datazoo.example.com/carbon288</span><span style="color: red;">/study92/location18/day96.xlsx</span></code><br/>
<code><span style="font-family: Arial , sans-serif;">\</span>__________________________________<em>/\</em>____________________________/</code><br/>
<code> <span style="color: blue;">ancestor's target URL</span> <span style="color: red;">suffix</span></code><br/>
</div>
<p>Note that SPT is only useful when the target server can respond to the suffixes it receives. For example, you would not instruct users how to add suffixes to the above ARK unless the target server was prepared to provide access to its 10,000 sub-objects. Fortunately, SPT is easy to illustrate in some cases, such as when the target server extends resource names with query strings or ordinary URL paths.</p>
<div class="pre-block">
<code><strong><em>Rule: if identifier A has target <span style="color: blue;">T</span>, suffix passthrough means the extended identifier A/<span style="color: red;">X</span> has target<span style="color: blue;">T</span>/<span style="color: red;">X</span></em></strong>.</code><br/>
</div>
<p>Using more words, for an identifier A stored in N2T that has the target URL T, if you add a suffix X to A and resolve (eg, click on) the URL A/X, you will be redirected to the URL T/X.</p>
<p>Some limitations and exceptions apply. For example, during the backwards scan, potential ancestor ARKs are tested (to see if they are registered) only at each "word" boundary, where a word here means a string of letters and digits. Also, scanning stops when the NAAN (the 5-digit number after the "ark:/") is reached.</p>
<h2 class="heading_2">Suffix Passthrough Examples</h2>
<p>You can see SPT in action by clicking on the extended ARKs below. These are "ARKs" (for illustration purposes only, not long-term stable) that <em>
are not</em> registered in the <a href="http://n2t.net" class="ext-link" rel="nofollow"><span style="color: blue;">N2T</span></a> resolver, but are formed by adding a <span style="color: red;">suffix</span> to an ARK that <em>is</em> registered.</p>
<p>Example 1. One registration standing in for several CDL service page "ARKs".</p>
<ul>
<li>Registered: ark:/12345/fk1234</li>
<li>Its target URL: <a href="http://www.cdlib.org/services" class="external-link" rel="nofollow"><span style="color: blue;">http://www.cdlib.org/services</span></a></li>
<li>An extended ARK: <a href="http://n2t.net/ark:/12345/fk1234/uc3/ezid/" class="external-link" rel="nofollow"><span style="color: blue;">http://n2t.net/ark:/12345/fk1234</span><span style="color: red;">/uc3/ezid/</span></a></li>
</ul>
<p>Example 2. One registration standing in for any number of Wikipedia article "ARKs".</p>
<ul>
<li>Registered: ark:/12345/fk1235</li>
<li>Its target URL: <a href="http://en.wikipedia.org/wiki" class="external-link" rel="nofollow"><span style="color: blue;">http://en.wikipedia.org/wiki</span></a></li>
<li>An extended ARK: <a href="http://n2t.net/ark:/12345/fk1235/Persistent_identifier" class="external-link" rel="nofollow"><span style="color: blue;">http://n2t.net/ark:/12345/fk1235</span><span style="color: red;">/Persistent_identifier</span></a></li>
</ul>
<p>Example 3. One registration standing in for any number of internet search "ARKs".</p>
<ul>
<li>Registered: ark:/12345/fk3</li>
<li>Its target URL: <a href="http://www.google.com/#q=" class="external-link" rel="nofollow"><span style="color: blue;">http://www.google.com/#q=</span></a></li>
<li>Extended ARK: <a href="http://n2t.net/ark:/12345/fk3pqrst" class="external-link" rel="nofollow"><span style="color: blue;">http://n2t.net/ark:/12345/fk3</span><span style="color: red;">pqrst</span></a></li>
</ul>
<p>You can experiment easily by pasting this registered ARK,</p>
<div class="pre-block">
<code>http://n2t.net/ark:/12345/fk3</code><br/>
</div>
<p>into your browser's location field and appending (no spaces) a "search term" suffix of your choice.</p>
{% endblocktrans %}
</div>
{% endblock %}