Skip to content

Latest commit

 

History

History
152 lines (114 loc) · 7.44 KB

ORGANIZATIONS_API.md

File metadata and controls

152 lines (114 loc) · 7.44 KB
Raw

Migrated as of May 2024

As of May 2024, the organizations API has been migrated to the HackGreenville.com and the associated Laravel HackGreenville repository.

The new Organizations API has less filtering options. The only filter is using "tags". So, API calls would look like

  • https://hackgreenville.com/api/v0/orgs - show all organizations
  • https://hackgreenville.com/api/v0/orgs?tags=1 - show all organizations with a tag ID = 1 (which is the tag for OpenWorks Coworking)

The list of organizations, and org details, can still be viewed on the HackGreenville website.

The Events API is still active.

If you have a use case to query organizations, instead of events, then reach out to the folks at HackGreenville Labs.

===============================================================================

Here's a start to documentation for interacting with the Organizations APIs.

You'll want a tool that makes it easy to send HTTP requests to the rest API. For instance, Guzzle is a handy package 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?

(Deprecated) Organizations API

Viewing, creating, and updating organizations.

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"
        }
    ]
}