'curl' Examples

'curl' allows you to perform web related actions that would normally be associated with a web brower or other dedicated application on the command-line. The command below shows a fairly complete example of how various things are passed. The '-X' flag is used to pass the HTTP verb - the default is 'GET'. The '-H' flag is used to pass any headers. The '-d' flag is used to pass any body data.

curl -X PUT -u username:password https://example.com/api/endpoint/ \
     -H "Content-Type: application/json" \
     -d '{"key":"value"}'

Currently, the Web API Bridge expects that any parameters will be passed as search parameters. The response returned is the result of the stored procedure called encoded in JSON format.

Configure API endpoint.

First you will need to configure your API endpoint. All you need to do is create an appropriate mapping between an domain starting with api and the IP address of the VM running the Web API Bridge. For example:

10.0.0.50 api-baseschema.local

If the Web API Bridge is correctly configured, navigating to this URL should show the PHP info page. Remember to specify the port 8080.

An Admin Account

If you haven't already, you should set up an admin account in your BaseSchema database (don't confuse this account with the MySQL Admin Account). To create an admin account login to MySQL, select the appropriate database, then enter the following:

CALL Users_Create_Admin( 'password' );

Of course, you can choose whichever password you wish. In the following examples, you will now be able to enter the username 'admin', and password 'password', in order to create a valid ADMIN session ID.

Authetication

To authenticate the 'Users_Sessions_Replace' stored procedure is used to create a new session.

curl -X POST http://api-baseschema.local:8080/api/users/sessions/replace/ \
     -d email=admin \
     -d password=password \

Response

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "",
    "status"    : "OK",
    "results"   : [{"status":"OK","sessionid":"5757e47cfb4a542c8bbb32e5d2bc15008096773d75e9f4b5d98af6fcc58b8189","USER":"1","idtype":"ADMIN"}],
    "warning"   : "",
    "URL"       : "/api/users/sessions/replace/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 2995
}

The sessionid that is returned is passed as the Sid parameter for each call that requires authorisation.

Pre-registrations

Launch pages are popular for web sites to guage the initial traction of an idea. Such sites typically allows users to submit their email, and potentially also name, so that they may be contacted later when the site officially launches.

The Base Schema contains the 'preregistrations' table, and associated stored procedures. The following curl will post a user's details to the database.

curl -X POST http://api-baseschema.local:8080/api/preregistrations/replace/ \
     -d name="James T. Kirk" \
     -d email="kirk@enterprise.com" \
     -d info="Initial Launch"

Response

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "",
    "status"    : "OK",
    "results"   : [{"status":"OK","token":"5abbbb5f62a95b4db03d34378d6cb0eee9aa26b30ebee7676853bcdd16be401f"}],
    "warning"   : "",
    "URL"       : "/api/preregistrations/replace/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 1317
}

The token within the response is a user confirmation token. This token may be sent to the user within a URL.

curl -X POST http://api-baseschema.local:8080/api/preregistrations/confirm/ \
    -d token=fc9aad6b007eaa67d764305426dbc7557a556dc37a02f86b4b4cc7d175d48ddf

Response

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "SQL: CALL preregistrations_confirm( '5abbbb5f62a95b4db03d34378d6cb0eee9aa26b30ebee7676853bcdd16be401f' ) : (TRUE)",
    "status"    : "OK",
    "results"   : [],
    "warning"   : "",
    "URL"       : "/api/preregistrations/confirm/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 1072
}

Altenatively, the 'preregistrations_unsent' proceure may be called to retrieve a list of people that have signed up, but who have not yet been sent an email.

curl -X POST http://api-baseschema.local:8080/api/preregistrations/unsent/ \
     -d sid=LOCAL

Response

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "",
    "status"    : "OK",
    "results"   :
        [
            {
                "name"              : "James T. Kirk",
                "email"             : "kirk@enterprise.com",
                "info"              : "Initial Launch",
                "token"             : "5abbbb5f62a95b4db03d34378d6cb0eee9aa26b30ebee7676853bcdd16be401f",
                "created"           : "2017-03-05 17:05:21",
                "confirmation_sent" : "0000-00-00 00:00:00",
                "confirmed"         : "2017-03-05 17:32:00",
                "TID"               : "kirk@enterprise.com"
            }
        ],
    "warning"   : "",
    "URL"       : "/api/preregistrations/unsent/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 1099
}

Once an email has been sent, the 'Preregistrations_Sent' procedure may be called to updated the 'confirmation_sent' field.

curl -X POST http://api-baseschema.local:8080/api/preregistrations/sent/ \
     -d sid=LOCAL \
     -d TID=kirk@enterprise.com

Response

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "SQL: CALL preregistrations_sent( 'LOCAL', 'kirk@enterprise.com' ) : (TRUE)",
    "status"    : "OK",
    "results"   : [],
    "warning"   : "",
    "URL"       : "/api/preregistrations/sent/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 1562
}

Users

Users can signup using the 'users_ First we will try to get a list of users. The output shown below has been formatte to make it more readable.

curl -X POST http://api.baseschema.local:8080/api/users/

{
    "error"     : "",
    "failover"  : "FALSE",
    "hostname"  : "localhost (DB_HOSTNAME)",
    "message"   : "SQL: CALL users_retrieve( '', '' ) : (TRUE)",
    "status"    : "OK",
    "results"   : [],
    "warning"   : "",
    "URL"       : "/api/users/",
    "target_id" : "",
    "submit"    : "",
    "limit"     : "",
    "offset"    : "",
    "microsecs" : 997
}