€cdocutils.nodes document q)q}q(U nametypesq}q(XgoalqNXtriggersqNX*use case 01 - get object identified by pidqNXsummaryq NX preconditionsq NXpost conditionsq NXuc01q ˆXactorsq NXhistoryqˆuUsubstitution_defsq}qUparse_messagesq]qUcurrent_sourceqNU decorationqNUautofootnote_startqKUnameidsq}q(hUgoalqhUtriggersqhU(use-case-01-get-object-identified-by-pidqh Usummaryqh U preconditionsqh Upost-conditionsqh Uuc01qh UactorsqhUhistoryq uUchildrenq!]q"(cdocutils.nodes target q#)q$}q%(U rawsourceq&X .. _UC01:Uparentq'hUsourceq(Xj/var/lib/jenkins/jobs/API_Documentation_trunk/workspace/api-documentation/source/design/UseCases/01_uc.txtq)Utagnameq*Utargetq+U attributesq,}q-(Uidsq.]Ubackrefsq/]Udupnamesq0]Uclassesq1]Unamesq2]Urefidq3huUlineq4KUdocumentq5hh!]ubcdocutils.nodes section q6)q7}q8(h&Uh'hh(h)Uexpect_referenced_by_nameq9}q:h h$sh*Usectionq;h,}q<(h0]h1]h/]h.]q=(hheh2]q>(hh euh4Kh5hUexpect_referenced_by_idq?}q@hh$sh!]qA(cdocutils.nodes title qB)qC}qD(h&X*Use Case 01 - Get Object Identified by PIDqEh'h7h(h)h*UtitleqFh,}qG(h0]h1]h/]h.]h2]uh4Kh5hh!]qHcdocutils.nodes Text qIX*Use Case 01 - Get Object Identified by PIDqJ…qK}qL(h&hEh'hCubaubcsphinx.addnodes index qM)qN}qO(h&Uh'h7h(h)h*UindexqPh,}qQ(h.]h/]h0]h1]h2]UentriesqR]qS((UsingleqTX Use Case 01Uindex-0qUUNtqV(hTXgethUUNtqW(hTXUC01hUUNtqXeUinlineqY‰uh4Kh5hh!]ubh#)qZ}q[(h&Uh'h7h(h)h*h+h,}q\(h.]h/]h0]h1]h2]h3hUuh4Kh5hh!]ubh6)q]}q^(h&Uh'h7h(h)h9}h*h;h,}q_(h0]h1]h/]h.]q`(hhUeh2]qahauh4K h5hh?}qbhUhZsh!]qc(hB)qd}qe(h&XGoalqfh'h]h(h)h*hFh,}qg(h0]h1]h/]h.]h2]uh4K h5hh!]qhhIXGoalqi…qj}qk(h&hfh'hdubaubcdocutils.nodes paragraph ql)qm}qn(h&X%Retrieve an object identified by PID.qoh'h]h(h)h*U paragraphqph,}qq(h0]h1]h/]h.]h2]uh4K h5hh!]qrhIX%Retrieve an object identified by PID.qs…qt}qu(h&hoh'hmubaubeubh6)qv}qw(h&Uh'h7h(h)h*h;h,}qx(h0]h1]h/]h.]qyhah2]qzh auh4Kh5hh!]q{(hB)q|}q}(h&XSummaryq~h'hvh(h)h*hFh,}q(h0]h1]h/]h.]h2]uh4Kh5hh!]q€hIXSummaryq…q‚}qƒ(h&h~h'h|ubaubhl)q„}q…(h&XJA client has an identifier for some object within the DataONE system and is attempting to retrieve the referenced object from a node (Member Node or Coordinating Node). If the object exists on the node and the user has READ permission on the object, then the bytes of that object are returned, otherwise an error condition occurs.q†h'hvh(h)h*hph,}q‡(h0]h1]h/]h.]h2]uh4Kh5hh!]qˆhIXJA client has an identifier for some object within the DataONE system and is attempting to retrieve the referenced object from a node (Member Node or Coordinating Node). If the object exists on the node and the user has READ permission on the object, then the bytes of that object are returned, otherwise an error condition occurs.q‰…qŠ}q‹(h&h†h'h„ubaubhl)qŒ}q(h&XQThis low level operation assumes that the client knows that the desired object is available on the target node. The normal process for retrieving an object given only the identifier is to first resolve the object, then retrieve the object from one of the identified nodes. Resolution is described in :doc:`UC36 `.h'hvh(h)h*hph,}qŽ(h0]h1]h/]h.]h2]uh4Kh5hh!]q(hIX,This low level operation assumes that the client knows that the desired object is available on the target node. The normal process for retrieving an object given only the identifier is to first resolve the object, then retrieve the object from one of the identified nodes. Resolution is described in q…q‘}q’(h&X,This low level operation assumes that the client knows that the desired object is available on the target node. The normal process for retrieving an object given only the identifier is to first resolve the object, then retrieve the object from one of the identified nodes. Resolution is described in h'hŒubcsphinx.addnodes pending_xref q“)q”}q•(h&X$:doc:`UC36 `q–h'hŒh(h)h*U pending_xrefq—h,}q˜(UreftypeXdocq™UrefwarnqšˆU reftargetq›X/design/UseCases/36_ucU refdomainUh.]h/]U refexplicitˆh0]h1]h2]UrefdocqœXdesign/UseCases/01_ucquh4Kh!]qžcdocutils.nodes inline qŸ)q }q¡(h&h–h,}q¢(h0]h1]q£(Uxrefq¤h™eh/]h.]h2]uh'h”h!]q¥hIXUC36q¦…q§}q¨(h&Uh'h ubah*hYubaubhIX.…q©}qª(h&X.h'hŒubeubeubh6)q«}q¬(h&Uh'h7h(h)h*h;h,}q­(h0]h1]h/]h.]q®hah2]q¯h auh4Kh5hh!]q°(hB)q±}q²(h&XActorsq³h'h«h(h)h*hFh,}q´(h0]h1]h/]h.]h2]uh4Kh5hh!]qµhIXActorsq¶…q·}q¸(h&h³h'h±ubaubcdocutils.nodes bullet_list q¹)qº}q»(h&Uh'h«h(h)h*U bullet_listq¼h,}q½(Ubulletq¾X-h.]h/]h0]h1]h2]uh4Kh5hh!]q¿(cdocutils.nodes list_item qÀ)qÁ}qÂ(h&XClient requesting objectqÃh'hºh(h)h*U list_itemqÄh,}qÅ(h0]h1]h/]h.]h2]uh4Nh5hh!]qÆhl)qÇ}qÈ(h&hÃh'hÁh(h)h*hph,}qÉ(h0]h1]h/]h.]h2]uh4Kh!]qÊhIXClient requesting objectqË…qÌ}qÍ(h&hÃh'hÇubaubaubhÀ)qÎ}qÏ(h&XCoordinating NodeqÐh'hºh(h)h*hÄh,}qÑ(h0]h1]h/]h.]h2]uh4Nh5hh!]qÒhl)qÓ}qÔ(h&hÐh'hÎh(h)h*hph,}qÕ(h0]h1]h/]h.]h2]uh4K h!]qÖhIXCoordinating Nodeq×…qØ}qÙ(h&hÐh'hÓubaubaubhÀ)qÚ}qÛ(h&X Member Node h'hºh(h)h*hÄh,}qÜ(h0]h1]h/]h.]h2]uh4Nh5hh!]qÝhl)qÞ}qß(h&X Member Nodeqàh'hÚh(h)h*hph,}qá(h0]h1]h/]h.]h2]uh4K!h!]qâhIX Member Nodeqã…qä}qå(h&hàh'hÞubaubaubeubeubh6)qæ}qç(h&Uh'h7h(h)h*h;h,}qè(h0]h1]h/]h.]qéhah2]qêh auh4K$h5hh!]që(hB)qì}qí(h&X Preconditionsqîh'hæh(h)h*hFh,}qï(h0]h1]h/]h.]h2]uh4K$h5hh!]qðhIX Preconditionsqñ…qò}qó(h&hîh'hìubaubh¹)qô}qõ(h&Uh'hæh(h)h*h¼h,}qö(h¾X-h.]h/]h0]h1]h2]uh4K&h5hh!]q÷hÀ)qø}qù(h&XvClient has authenticated to the desired level (e.g. client may not have authenticated, so access might be anonymous). h'hôh(h)h*hÄh,}qú(h0]h1]h/]h.]h2]uh4Nh5hh!]qûhl)qü}qý(h&XuClient has authenticated to the desired level (e.g. client may not have authenticated, so access might be anonymous).qþh'høh(h)h*hph,}qÿ(h0]h1]h/]h.]h2]uh4K&h!]rhIXuClient has authenticated to the desired level (e.g. client may not have authenticated, so access might be anonymous).r…r}r(h&hþh'hüubaubaubaubeubh6)r}r(h&Uh'h7h(h)h*h;h,}r(h0]h1]h/]h.]rhah2]rhauh4K*h5hh!]r (hB)r }r (h&XTriggersr h'jh(h)h*hFh,}r (h0]h1]h/]h.]h2]uh4K*h5hh!]rhIXTriggersr…r}r(h&j h'j ubaubh¹)r}r(h&Uh'jh(h)h*h¼h,}r(h¾X-h.]h/]h0]h1]h2]uh4K,h5hh!]rhÀ)r}r(h&X0An object is requested from the DataONE system. h'jh(h)h*hÄh,}r(h0]h1]h/]h.]h2]uh4Nh5hh!]rhl)r}r(h&X/An object is requested from the DataONE system.rh'jh(h)h*hph,}r(h0]h1]h/]h.]h2]uh4K,h!]rhIX/An object is requested from the DataONE system.r…r }r!(h&jh'jubaubaubaubeubh6)r"}r#(h&Uh'h7h(h)h*h;h,}r$(h0]h1]h/]h.]r%hah2]r&h auh4K/h5hh!]r'(hB)r(}r)(h&XPost Conditionsr*h'j"h(h)h*hFh,}r+(h0]h1]h/]h.]h2]uh4K/h5hh!]r,hIXPost Conditionsr-…r.}r/(h&j*h'j(ubaubh¹)r0}r1(h&Uh'j"h(h)h*h¼h,}r2(h¾X-h.]h/]h0]h1]h2]uh4K1h5hh!]r3(hÀ)r4}r5(h&XWThe client has a copy of the object bytes (or an error message in the case of failure) h'j0h(h)h*hÄh,}r6(h0]h1]h/]h.]h2]uh4Nh5hh!]r7hl)r8}r9(h&XVThe client has a copy of the object bytes (or an error message in the case of failure)r:h'j4h(h)h*hph,}r;(h0]h1]h/]h.]h2]uh4K1h!]r<hIXVThe client has a copy of the object bytes (or an error message in the case of failure)r=…r>}r?(h&j:h'j8ubaubaubhÀ)r@}rA(h&XHThe :term:`node event log` is updated with the results of the operation h'j0h(h)h*hÄh,}rB(h0]h1]h/]h.]h2]uh4Nh5hh!]rChl)rD}rE(h&XGThe :term:`node event log` is updated with the results of the operationh'j@h(h)h*hph,}rF(h0]h1]h/]h.]h2]uh4K4h!]rG(hIXThe rH…rI}rJ(h&XThe h'jDubh“)rK}rL(h&X:term:`node event log`rMh'jDh(h)h*h—h,}rN(UreftypeXtermhšˆh›Xnode event logU refdomainXstdrOh.]h/]U refexplicit‰h0]h1]h2]hœhuh4K4h!]rPhŸ)rQ}rR(h&jMh,}rS(h0]h1]rT(h¤jOXstd-termrUeh/]h.]h2]uh'jKh!]rVhIXnode event logrW…rX}rY(h&Uh'jQubah*hYubaubhIX- is updated with the results of the operationrZ…r[}r\(h&X- is updated with the results of the operationh'jDubeubaubhÀ)r]}r^(h&X%Watchers are notified of the event. h'j0h(h)h*hÄh,}r_(h0]h1]h/]h.]h2]uh4Nh5hh!]r`hl)ra}rb(h&X#Watchers are notified of the event.rch'j]h(h)h*hph,}rd(h0]h1]h/]h.]h2]uh4K6h!]rehIX#Watchers are notified of the event.rf…rg}rh(h&jch'jaubaubaubeubcsphinxcontrib.plantuml plantuml ri)rj}rk(h&Xð.. uml:: @startuml images/01_uc.png actor "User" as client usecase "12. Authentication" as authen note top of authen Authentication may be provided by an external service end note actor "Coordinating Node" as CN actor "Member Node" as MN usecase "13. Authorization" as author usecase "01. Get Object" as GET usecase "16. Log event" as log usecase "21. Notify subscribers" as subscribe usecase "36. Resolve object" as resolve client -- GET CN -- GET MN -- GET GET ..> author: <>\n[optional] GET ..> authen: <>\n[optional] GET ..> log: <> GET ..> subscribe: <> GET ..> resolve: <>\n[optional] @enduml h'j"h(h)h*Uplantumlrlh,}rm(h.]h/]h0]h1]h2]UumlrnXŸ@startuml images/01_uc.png actor "User" as client usecase "12. Authentication" as authen note top of authen Authentication may be provided by an external service end note actor "Coordinating Node" as CN actor "Member Node" as MN usecase "13. Authorization" as author usecase "01. Get Object" as GET usecase "16. Log event" as log usecase "21. Notify subscribers" as subscribe usecase "36. Resolve object" as resolve client -- GET CN -- GET MN -- GET GET ..> author: <>\n[optional] GET ..> authen: <>\n[optional] GET ..> log: <> GET ..> subscribe: <> GET ..> resolve: <>\n[optional] @endumluh4KUh5hh!]ubhl)ro}rp(h&XX**Figure 1.** Use case 01 diagram showing actors and components involved in this action.h'j"h(h)h*hph,}rq(h0]h1]h/]h.]h2]uh4KVh5hh!]rr(cdocutils.nodes strong rs)rt}ru(h&X **Figure 1.**h,}rv(h0]h1]h/]h.]h2]uh'joh!]rwhIX Figure 1.rx…ry}rz(h&Uh'jtubah*Ustrongr{ubhIXK Use case 01 diagram showing actors and components involved in this action.r|…r}}r~(h&XK Use case 01 diagram showing actors and components involved in this action.h'joubeubcdocutils.nodes image r)r€}r(h&X.. image:: images/01_seq.png h'j"h(h)h*Uimager‚h,}rƒ(UuriX!design/UseCases/images/01_seq.pngr„h.]h/]h0]h1]U candidatesr…}r†U*j„sh2]uh4K\h5hh!]ubji)r‡}rˆ(h&X¹.. uml:: @startuml images/01_seq.png participant "Client" as app_client << Application >> participant "Read API" as n_crud << Node >> participant "Authorization API" as n_authorize << Node >> participant "Object Store" as n_ostore << Node >> app_client -> n_crud: get(session, PID) n_crud -> n_authorize: isAuthorized(session, PID, READ) n_crud <- n_authorize: True, False, Err.NotFound alt NotFound app_client <- n_crud: Err.NotFound else False app_client <- n_crud: Err.NotAuthorized else True n_crud -> n_ostore: read(PID) n_crud <- n_ostore: bytes n_crud --> n_crud: log(PID, READ) app_client <- n_crud: bytes end @enduml h'j"h(h)h*jlh,}r‰(h.]h/]h0]h1]h2]jnXt@startuml images/01_seq.png participant "Client" as app_client << Application >> participant "Read API" as n_crud << Node >> participant "Authorization API" as n_authorize << Node >> participant "Object Store" as n_ostore << Node >> app_client -> n_crud: get(session, PID) n_crud -> n_authorize: isAuthorized(session, PID, READ) n_crud <- n_authorize: True, False, Err.NotFound alt NotFound app_client <- n_crud: Err.NotFound else False app_client <- n_crud: Err.NotAuthorized else True n_crud -> n_ostore: read(PID) n_crud <- n_ostore: bytes n_crud --> n_crud: log(PID, READ) app_client <- n_crud: bytes end @endumluh4Ksh5hh!]ubhl)rŠ}r‹(h&X **Figure 2.** Sequence diagram for Use Case 01 illustrating the sequence for retrieving an object identified by a PID from the DataONE system. No distinction is made between Member Node and Coordinating Node implementation as they are identical at this level of detail.h'j"h(h)h*hph,}rŒ(h0]h1]h/]h.]h2]uh4Kth5hh!]r(js)rŽ}r(h&X **Figure 2.**h,}r(h0]h1]h/]h.]h2]uh'jŠh!]r‘hIX Figure 2.r’…r“}r”(h&Uh'jŽubah*j{ubhIX Sequence diagram for Use Case 01 illustrating the sequence for retrieving an object identified by a PID from the DataONE system. No distinction is made between Member Node and Coordinating Node implementation as they are identical at this level of detail.r•…r–}r—(h&X Sequence diagram for Use Case 01 illustrating the sequence for retrieving an object identified by a PID from the DataONE system. No distinction is made between Member Node and Coordinating Node implementation as they are identical at this level of detail.h'jŠubeubhl)r˜}r™(h&X **Notes**ršh'j"h(h)h*hph,}r›(h0]h1]h/]h.]h2]uh4K{h5hh!]rœjs)r}rž(h&jšh,}rŸ(h0]h1]h/]h.]h2]uh'j˜h!]r hIXNotesr¡…r¢}r£(h&Uh'jubah*j{ubaubcdocutils.nodes enumerated_list r¤)r¥}r¦(h&Uh'j"h(h)h*Uenumerated_listr§h,}r¨(Usuffixr©U.h.]h/]h0]UprefixrªUh1]h2]Uenumtyper«Uarabicr¬uh4K}h5hh!]r­(hÀ)r®}r¯(h&XçFor the GET operation, should isAuth() be performed only by CNs? Relying on the MN system metadata requires trusted implementation of the MN system and consistency of system metadata across all MNs (which will be the case, though with uncertain latency). Requiring all isAuth() operations to be performed by CNs will increase trust in the operation (assuming the operation is not spoofed by a MN) though will increase load on CNs. This should be specified in the Authorization use case. h'j¥h(h)h*hÄh,}r°(h0]h1]h/]h.]h2]uh4Nh5hh!]r±hl)r²}r³(h&XæFor the GET operation, should isAuth() be performed only by CNs? Relying on the MN system metadata requires trusted implementation of the MN system and consistency of system metadata across all MNs (which will be the case, though with uncertain latency). Requiring all isAuth() operations to be performed by CNs will increase trust in the operation (assuming the operation is not spoofed by a MN) though will increase load on CNs. This should be specified in the Authorization use case.r´h'j®h(h)h*hph,}rµ(h0]h1]h/]h.]h2]uh4K}h!]r¶hIXæFor the GET operation, should isAuth() be performed only by CNs? Relying on the MN system metadata requires trusted implementation of the MN system and consistency of system metadata across all MNs (which will be the case, though with uncertain latency). Requiring all isAuth() operations to be performed by CNs will increase trust in the operation (assuming the operation is not spoofed by a MN) though will increase load on CNs. This should be specified in the Authorization use case.r·…r¸}r¹(h&j´h'j²ubaubaubhÀ)rº}r»(h&X[Data sent to watchers might include: timestamp, object identifier, user id, IP of client. h'j¥h(h)h*hÄh,}r¼(h0]h1]h/]h.]h2]uh4Nh5hh!]r½hl)r¾}r¿(h&XYData sent to watchers might include: timestamp, object identifier, user id, IP of client.rÀh'jºh(h)h*hph,}rÁ(h0]h1]h/]h.]h2]uh4K…h!]rÂhIXYData sent to watchers might include: timestamp, object identifier, user id, IP of client.rÃ…rÄ}rÅ(h&jÀh'j¾ubaubaubeubh#)rÆ}rÇ(h&X¡.. _history: https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/design/UseCases/01_uc.txth'j"h(h)h*h+h,}rÈ(UrefurirÉX”https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/design/UseCases/01_uc.txth.]rÊh ah/]h0]h1]h2]rËhauh4K‰h5hh!]ubeubeubeh&UU transformerrÌNU footnote_refsrÍ}rÎUrefnamesrÏ}rÐUsymbol_footnotesrÑ]rÒUautofootnote_refsrÓ]rÔUsymbol_footnote_refsrÕ]rÖU citationsr×]rØh5hU current_linerÙNUtransform_messagesrÚ]rÛ(cdocutils.nodes system_message rÜ)rÝ}rÞ(h&Uh,}rß(h0]UlevelKh.]h/]Usourceh)h1]h2]UlineKUtypeUINFOràuh!]ráhl)râ}rã(h&Uh,}rä(h0]h1]h/]h.]h2]uh'jÝh!]råhIX*Hyperlink target "uc01" is not referenced.ræ…rç}rè(h&Uh'jâubah*hpubah*Usystem_messageréubjÜ)rê}rë(h&Uh,}rì(h0]UlevelKh.]h/]Usourceh)h1]h2]UlineKUtypejàuh!]ríhl)rî}rï(h&Uh,}rð(h0]h1]h/]h.]h2]uh'jêh!]rñhIX-Hyperlink target "index-0" is not referenced.rò…ró}rô(h&Uh'jîubah*hpubah*jéubjÜ)rõ}rö(h&Uh,}r÷(h0]UlevelKh.]h/]Usourceh)h1]h2]UlineK‰Utypejàuh!]røhl)rù}rú(h&Uh,}rû(h0]h1]h/]h.]h2]uh'jõh!]rühIX-Hyperlink target "history" is not referenced.rý…rþ}rÿ(h&Uh'jùubah*hpubah*jéubeUreporterrNUid_startrKU autofootnotesr]rU citation_refsr}rUindirect_targetsr]rUsettingsr(cdocutils.frontend Values r or }r (Ufootnote_backlinksr KUrecord_dependenciesr NU rfc_base_urlrUhttps://tools.ietf.org/html/rU tracebackrˆUpep_referencesrNUstrip_commentsrNU toc_backlinksrUentryrU language_coderUenrU datestamprNU report_levelrKU _destinationrNU halt_levelrKU strip_classesrNhFNUerror_encoding_error_handlerrUbackslashreplacerUdebugrNUembed_stylesheetr‰Uoutput_encoding_error_handlerr Ustrictr!U sectnum_xformr"KUdump_transformsr#NU docinfo_xformr$KUwarning_streamr%NUpep_file_url_templater&Upep-%04dr'Uexit_status_levelr(KUconfigr)NUstrict_visitorr*NUcloak_email_addressesr+ˆUtrim_footnote_reference_spacer,‰Uenvr-NUdump_pseudo_xmlr.NUexpose_internalsr/NUsectsubtitle_xformr0‰U source_linkr1NUrfc_referencesr2NUoutput_encodingr3Uutf-8r4U source_urlr5NUinput_encodingr6U utf-8-sigr7U_disable_configr8NU id_prefixr9UU tab_widthr:KUerror_encodingr;UUTF-8r<U_sourcer=h)Ugettext_compactr>ˆU generatorr?NUdump_internalsr@NU smart_quotesrA‰U pep_base_urlrBU https://www.python.org/dev/peps/rCUsyntax_highlightrDUlongrEUinput_encoding_error_handlerrFj!Uauto_id_prefixrGUidrHUdoctitle_xformrI‰Ustrip_elements_with_classesrJNU _config_filesrK]Ufile_insertion_enabledrLˆU raw_enabledrMKU dump_settingsrNNubUsymbol_footnote_startrOKUidsrP}rQ(hj"hh7hh]hjhhvhUh]hh«hh7hhæh jÆuUsubstitution_namesrR}rSh*h5h,}rT(h0]h.]h/]Usourceh)h1]h2]uU footnotesrU]rVUrefidsrW}rX(h]rYh$ahU]rZhZauub.