kinlane
9/7/2017 - 2:23 PM

FOIA API Draft Request - OpenAP

FOIA API Draft Request - OpenAP

swagger: "2.0"
info:
  title: FOIA.gov API (Draft)
  description: This is a draft spec for integrating the FOIA.gov portal with existing FOIA case management systems (e.g., FOIAonline) in the federal government. This work stems from the interviews and research that led to our FOIA Portal Discovery Recommendations.
  version: 1.0.0
host:  api.data.gov
basePath: /
schemes:
  - https
produces:
  - application/json
consumes:
  - application/json
paths:
  /components/{id}/requests/:
    post:
      summary: Submit FOIA Request
      description: The agency component receiving the FOIA request.
      parameters:
        - in: path
          required: true
          type: string
          name: id
          description: The id of the request.
        - in: body
          name: body
          schema:
            $ref: '#/definitions/foia_request'
      responses:
        200:
          description: Confirm that the request was created and return an id that can uniquely identify the request in the case management system. The (optional) status tracking number can be used by a requester to track a request.
          schema:
            type: object
            items:
              $ref: '#/definitions/success_response_200'
        404:
          description: The target agency component specified in URI was not found (error payload includes a place for a system-specific message, to make it easier to track down problems)
          schema:
            type: object
            items:
              $ref: '#/definitions/error_response_404'
        500:
          description: The case management system encountered an internal error when trying to create the FOIA request (error payload includes a place for a system-specific message, to make it easier to track down problems)
          schema:
            type: object
            items:
              $ref: '#/definitions/error_response_500'
      tags:
        - FOIA
definitions:
  foia_request:
    properties:
      agency_name:
        description: Name of the tier 1 agency.
        type: string
        example: Department of Justice
      agency_component_name:
        description: Name of the department, bureau, or office.
        type: string
        example: Office of Information Policy
      requester_name:
        description: A unique identiefer for the product.
        type: "object"
        items:
          $ref: "#/definitions/requester_name"
      requester_address:
        description: Mailing address of the requester.
        type: "object"
        items:
          $ref: "#/definitions/requester_address"
      description:
        description: Description of the records the requester is seeking.
        type: string
        example: I am seeking records pertaining to ...
      max_fee:
        description: TThe requester would like to request that fees associated with the request be waived.
        type: boolean
        example: 25.00
      fee_waiver:
        description: An image width for the product.
        type: boolean
        example: false
      expedited:
        description: The requester would like this request to be processed on an expedited basis.
        type: boolean
        example: false
      organization:
        description: Name of the organization or company on which the requester is making a request on behalf of.
        type: string
        example: Newspaper Inc
      email:
        description: Email address of the requester.
        type: string
        example:  george.washington@example.com
      phone:
        description: Phone number of the requester.
        type: string
        example: +15551234567
      fax:
        description: Fax number of the requester
        type: string
        example: +15551234589
      attachments:
        description: Documents or attachments supporting the request provided by the requester.
        type: array
        items:
          $ref: "#/definitions/attachments"
      agency_component_specific_fields:
        description: Agency component specific request form fields as specified in your agency's metadata file.
        type: array
        items:
          $ref: "#/definitions/agency_component_specific_fields"
    required:
      - agency_name  
      - agency_component_name               
      - requester_name        
      - requester_address  
      - description  
      - email  
  requester_name:
    properties:
      first:
        description: The name of the requester.
        type: string
      last:
        description: The name of the requester.
        type: string
    required:
      - first  
      - last     
  requester_address:
    properties:
      address1:
        description: The adress1 of the requester.
        type: string
      address2:
        description: The address2 of the requester.
        type: string
      city:
        description: The city of the requester.
        type: string
      state:
        description: The state of the requester.
        type: string
      zip:
        description: The city of the requester.
        type: string
    required:
      - address1  
      - address2
      - city
      - state  
      - zip
  attachments:
    properties:
      filename:
        description: The filename of the attachment.
        type: string
        example: letter.pdf
      content_type:
        description: The content type of the attachment.
        type: string
        example: application/pdf
      filesize:
        description: The file size of the attachment.
        type: integer
        example: 27556
      filedata:
        description: The file data of the attachment.
        type: string
        example: YSBiYXNlNjQgZW5jb2RlZCBmaWxlCg==
    required:
      - filename  
      - content_type
      - filesize
      - filedata
  agency_component_specific_fields:
    properties:
      form_460A_case_number:
        description: The form 460A case number.
        type: integer
        example: 3347
      requester_type:
        description: The requester type.
        type: string
        example: Journalist
  success_response_200:
    properties:
      id:
        description: The id of the request.
        type: integer
      status_tracking_number:
        description: The status tracking number of the request.
        type: string
  error_response_404:
    properties:
      code:
        description: The code of the error.
        type: string
      message:
        description: The message of the error.
        type: string
      description:
        description: The description of the error.
        type: string
  error_response_500:
    properties:
      code:
        description: The code of the error.
        type: string
      message:
        description: The message of the error.
        type: string
      description:
        description: The description of the error.
        type: string