New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

REST API Documentation #17

Open
allella opened this Issue Feb 16, 2015 · 3 comments

Comments

Projects
None yet
2 participants
@allella
Member

allella commented Feb 16, 2015

Last updated July 2018

Here's a start to documentation for viewing, creating, and updating organizations.

You'll want a tool that makes it easy to send HTTP requests to the rest API. For instance, Guzzle is a handy tool for PHP developers.

Some of the examples below are written for a test tool like Postman if you're running tests.

Need more background on REST testing / debugging tools?

List of All Organizations (Human/ Web Browser View)

URL

Method: GET
Expected Response: 200 OK
Authorization: None Required

REST API List of All Organizations (Robot View)

If you get an Access Denied (error 403) on while you're already logged into Drupal as another user then try to open the URL in an Incognito tab.

URL

Method: GET
Expected Response: 200 OK
Authorization: None Required
Headers - Drupal 8 REST does NOT support the Accept: header, so you MUST use the &_format= mentioned above. The reason for not supporting Accept: headers is documented.

Query String

Errors

If you get an HTML response that says "A client error happened" then you need to include/fix the _format= parameter.

Example of Viewing an Organization

URL: https://data.openupstate.org/node/7?_format=json OR the alias https://data.openupstate.org/organization/code-for-greenville?_format=json
Expected Response: 200 OK
Authorization: None Required

Set an accepted / desired content format

  • append &_format=json to the URL query string
  • append &_format=hal_json to the URL query string
  • append &_format=xml to the URL query string

Headers - Drupal 8 REST does NOT support the Accept: header, so you MUST use the &_format= mentioned above. The reason for not supporting Accept: headers is documented.

Example of Creating a New Organization

Method: POST
URL: https://data.openupstate.org/entity/node
Authorization: Requires Basic Auth and a user / password hash
Expected Response: 200 OK (serialized JSON of the full object) (no longer returns 201 Created)
Headers to Send

  • Content-Type: application/hal+json
  • X-CSRF-Token: (visit /rest/session/token to get a token and use that string here)

Drupal POST Documentation

Notes: The _links->type->href value is required with hal+json, as it defines the entity. Do a GET on any organization node beforehand to verify/check the fields. Drupal will automatically set core fields like like created, updated, promoted, status, so it's really only necessary to set the title and custom fields (field_xyz)
Predefined Field Values
If a value is sent for one of the following fields, it must be one of the following or the POST will fail.

  • field_event_service: eventbrite, facebook, meetup, none, nvite
  • field_org_status: active, inactive, on-hiatus, planned

Example Body

{ 
  "_links": {
    "type": { "href": "https://data.openupstate.org/rest/type/node/organization" }
  },
 "title": [ { "value": "Upstate AI Robot", "lang": "en" } ],
 "field_city": [ { "value": "spartanburg" } ],
 "field_event_service": [ { "value": "eventbrite" } ],
 "field_events_api_key": [ { "value": "123456789" } ],
 "field_focus_area": [ { "value": "Robots with Lasers" } ],
 "field_homepage": [ { "uri": "http://example.com/johnny-5" } ],
 "field_org_status": [ { "value": "active" } ],
 "field_primary_contact_email": [ { "value": "johnnyfive@example.com" } ],
 "field_primary_contact_person": [ { "value": "Johnny Five" } ]
}

Example of Updating an Organization

Method: PATCH (Drupal purposely does not support PUT)
URL: https://data.openupstate.org/node/4
Expected Response: 200 OK (serialized JSON of the full object)
Authorization: Requires Basic Auth and a user / password hash
Headers to Send

  • Content-Type: application/hal+json
  • X-CSRF-Token: (visit /rest/session/token to get a token and use that string here)

Drupal Patch Documentation

Notes: The _links->type->href value is required with hal+json, as it defines the entity. It is possible to update many fields at once by including multiple values in the body. This example updates only one field, field_primary_contact_person.

Predefined Field Values
If a value is sent for one of the following fields, it must be one of the following or the PATCH will fail.

  • field_event_service: eventbrite, facebook, meetup, none, nvite
  • field_org_status: active, inactive, on-hiatus, planned

Example Body

{
    "_links": {
        "type": {
            "href": "https://data.openupstate.org/rest/type/node/organization"
        }
    },
    "field_primary_contact_person": [
        {
            "value": "Johnny Five"
        }
    ]
}

Example of Updating a Map

{
    "_links": {
        "type": {
            "href": "https://data.openupstate.org/rest/type/node/map"
        }
    },
    "field_contribute_link": [
        {
            "uri": "https://docs.google.com/spreadsheets/d/1IQol1Gy8gRbQ0wT5YsO9IF_GazVcfbTx828zT9SvGwI/edit#gid=0",
            "title": "",
            "options": []
        }
    ],
    "field_geojson_link": [
        {
            "uri": "internal:/maps/bike-racks/geojson.php",
            "title": "",
            "options": []
        }
    ],
    "field_raw_data_link": [
        {
            "uri": "https://docs.google.com/spreadsheets/d/1IQol1Gy8gRbQ0wT5YsO9IF_GazVcfbTx828zT9SvGwI/pub?output=csv",
            "title": "",
            "options": []
        }
    ]
}

@allella allella changed the title from REST APIDocumentation to REST API Documentation Feb 16, 2015

@allella allella referenced this issue Mar 18, 2015

Closed

Imagine That.... #8

@allella

@allella allella added the tech-groups label May 9, 2017

@allella

This comment has been minimized.

Show comment
Hide comment
@allella

allella Jan 24, 2018

Member

@Nunie123 I've added tag field filter to the above, example:
tag_filter_id=1

Member

allella commented Jan 24, 2018

@Nunie123 I've added tag field filter to the above, example:
tag_filter_id=1

@Nunie123

This comment has been minimized.

Show comment
Hide comment
@Nunie123

Nunie123 Jan 26, 2018

@allella I've added tags as a filter to the events api. See my comment at Issue #12 .

Nunie123 commented Jan 26, 2018

@allella I've added tags as a filter to the events api. See my comment at Issue #12 .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment