834 | | |
835 | | |
836 | | |
| 834 | The following table contains required fields for member objects and whether they are allowed in lookup ‘match’ criteria and their protection (public, private, identifying): |
| 835 | |
| 836 | |
| 837 | || ''' Name ''' || ''' Type ''' || ''' Description ''' || ''' Match ''' || ''' Protection ''' || |
| 838 | || MEMBER_URN || URN || URN of given member || Yes || Public || |
| 839 | || MEMBER_UID ||UID || UID (unique within authority) of member || Yes || Public || |
| 840 | || MEMBER_FIRSTNAME || DATETIME || First name of member || Yes || Identifying || |
| 841 | || MEMBER_LASTNAME || DATETIME || Last name of member || Yes || Identifying || |
| 842 | || MEMBER_USERNAME || BOOLEAN || Username of user || Yes || Public || |
| 843 | || MEMBER_EMAIL || STRING || Email of user || No || Identifying || |
| 844 | |
| 845 | /* |
| 846 | |
| 847 | Return information about version and options (filter, query, credential types) accepted by this member authority |
| 848 | |
| 849 | NB: This is an unprotected call, no client cert required. |
| 850 | |
| 851 | '''Arguments:''' |
| 852 | |
| 853 | None |
| 854 | |
| 855 | '''Return:''' |
| 856 | |
| 857 | get_version structure information as described above |
| 858 | |
| 859 | */ |
| 860 | |
| 861 | function '''get_version'''() |
| 862 | |
| 863 | /* |
| 864 | Lookup public information about members matching given criteria |
| 865 | |
| 866 | NB: This is an unprotected call, no client cert required. |
| 867 | |
| 868 | '''Arguments:''' |
| 869 | |
| 870 | options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return |
| 871 | |
| 872 | '''Return:''' |
| 873 | |
| 874 | List of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria |
| 875 | |
| 876 | */ |
| 877 | |
| 878 | function '''lookup_public_member_info''' (options) |
| 879 | |
| 880 | /* |
| 881 | |
| 882 | Lookup private (SSL/SSH key) information about members matching given criteria |
| 883 | |
| 884 | '''Arguments:''' |
| 885 | |
| 886 | options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return |
| 887 | |
| 888 | '''Return:''' |
| 889 | |
| 890 | List of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria |
| 891 | |
| 892 | */ |
| 893 | |
| 894 | function '''lookup_private_member_info''' (credentials, options) |
| 895 | |
| 896 | /* |
| 897 | |
| 898 | Lookup identifying (e.g. name, email) info about matching members |
| 899 | |
| 900 | '''Arguments:''' |
| 901 | |
| 902 | options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return |
| 903 | |
| 904 | '''Return:''' |
| 905 | |
| 906 | List of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria |
| 907 | |
| 908 | */ |
| 909 | |
| 910 | function '''lookup_identifying_member_info''' (credentials, options) |
| 911 | |
| 912 | /* |
| 913 | |
| 914 | Update information about given member public, private or identifying information |
| 915 | |
| 916 | '''Arguments:''' |
| 917 | |
| 918 | member_urn: URN of member for whom to set information |
| 919 | |
| 920 | options: Containing ‘update’ key with dictionary of name/value pairs to update info for given member |
| 921 | |
| 922 | '''Return:''' |
| 923 | |
| 924 | None |
| 925 | |
| 926 | */ |
| 927 | |
| 928 | function '''update_member_info''' (member_urn, credentials, options) |
| 929 | |
| 930 | /* |
| 931 | |
| 932 | Provide list of credentials (signed statements) for given member |
| 933 | This is member-specific information suitable for passing as credentials in an AM API call for aggregate authorization. |
| 934 | |
| 935 | '''Arguments:''' |
| 936 | |
| 937 | member_urn: URN of member for which to retrieve credentials |
| 938 | |
| 939 | options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument) |
| 940 | |
| 941 | '''Return:''' |
| 942 | |
| 943 | List of credential in “CREDENTIAL_LIST” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3. |
| 944 | |
| 945 | */ |
| 946 | |
| 947 | function '''get_credentials'''(member_urn, credentials, options) |
| 948 | |
| 949 | == Appendix: CH Object Models == |
| 950 | |
| 951 | As described, each CH service method takes a set of options that provide further details on the request. Many of these options reflect the fields of the underlying object models. For example, the Slice Authority manages slice objects and allows for options for querying for and by slice object fields. |
| 952 | |
| 953 | Different Clearinghouses will implement different subsets of the possible set of CH services. Those that do implement a given service should implement the API’s described above. The fields of the objects maintained through these API’s are flexible: some fields are required but different Clearinghouses may have their own additional data, to be returned by the get_version method. |
| 954 | |
| 955 | The following diagram reflects the different objects maintained within the full range of CH services, their interactions and mandatory fields. |